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 (see) -- unable to automatically generate TOC besides using JavaScript. use travis CI and/or awestruct to generate and push automatically? (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
Comments