Choosing Documentation Platform for mod_cluster

Version 1


    Motivation / Goals


    • provide upstream project with reliable documentation
    • enable easy community and internal contributions
    • minimal management overhead




    • 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)




    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





    • needs community account
    • 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
    • reliablity