diff --git a/docs/src/main/asciidoc/developer/choosing_doc_platform.adoc b/docs/src/main/asciidoc/developer/choosing_doc_platform.adoc deleted file mode 100644 index 7f040b5..0000000 --- a/docs/src/main/asciidoc/developer/choosing_doc_platform.adoc +++ /dev/null @@ -1,112 +0,0 @@ -= Choosing Documentation Platform for mod_cluster - -== Motivation / Goals - -* provide upstream project with reliable documentation - -* enable easy community and internal contributions - -* minimal management overhead - -== Requirements - -* up to date "real-time" documentation (no pushing, merging, rebuilding) - -* reliable documentation hosting, high uptime - -* changelog of changes - -* vendor independent documentation - -* ability to link document sections (use to direct people in community to -particular sections) - -* maintain 1.1.x, 1.2.x, etc versions of the documentation (patch/cherry-pick -changes) - -== Candidates - -=== DocBook (XML) in Project Repository (current) - -**+** - -* easy to create other formats / generating PDFs - -**-** - -* stale documentation, needs manual rebuilding and publishing - -* need to maintain private infrastructure to host and push to - -* too complex for everyone (and chatty XML) - -* no community contributions (made better with subversion to git migration) - -=== GitHub Wiki - -**+** - -* out of box markdown - -* easy to setup - -* easy (actually too easy) to contibute - -**-** - -* anybody can edit, no review process! - -* needs a github account to contribute - -* slight dependency on github - -* unable to reasonably structure documentation - -=== GitHub Pages - -**+** - -* can contribute directly from github (no setup required at all!) - -* review changes with pull request process - -* little github depedency, repo could be moved elsewhere - -**-** - -* github pages don't support jekyll plugins -(https://help.github.com/articles/using-jekyll-plugins-with-github-pages[see]) -– unable to automatically generate TOC besides using JavaScript. use travis CI -and/or awestruct to generate and push automatically? -(http://awestruct.org/auto-deploy-to-github-pages/[see]) - -* needs a github account to contribute - -* need to use Jekyll to use markdown format - -=== Confluence - -**+** - -* needs jboss.org community account - -* WYSIWYG - -* changes are immediately published - -* comments - -**-** - -* vendor lock-in, documentation cannot be reasonably moved elsewhere - -* unable to see whole documentation in single page (verify) - -* comments can take more space than the actual content and cannot be deleted - -* fixes to 1.1.x, 1.2.x, etc have to be done manually - -* poor WYSIWYG - -* jboss.org reliablity - diff --git a/docs/src/main/asciidoc/developer/index.adoc b/docs/src/main/asciidoc/developer/index.adoc index ed0252b..9d6771d 100644 --- a/docs/src/main/asciidoc/developer/index.adoc +++ b/docs/src/main/asciidoc/developer/index.adoc @@ -37,7 +37,6 @@ include::design.adoc[] = Miscellaneous -* xref:choosing_doc_platform.adoc[Choosing Documentation Platform for mod_cluster] * xref:q_a_webinar.adoc[Questions and Answers on mod_cluster webinar] * xref:hw_load_balancer.adoc[Using a hardware load balancer in combination with mod_cluster server-side load metrics] * xref:fedora24_25_update_testing.adoc[mod_cluster 1.2.6.Final -> 1.3.3.Final in Fedora 24 and Fedora 25 updates-testing]