Usability - Productivity - Business - The web - Singapore & Twins

The Quest for a software documentation system

Software documentation is a thankless business and never complete. Picking the right system can make or break your documentation success


We have a number of options commonly used, each with strengh and weaknesses.

  • DITA: The OASIS Open Darwin Information Typing Architecture. Extremly powerful, especially the concept of single source definition: You define an item once and just reference it. XML based, suitable for complex documentation, but with a super steep learning curve, effectively prohibit community contributions
  • jekyll: Markdown driven template engine, best known for driving GitHub Pages. With the Just-the-docs template it makes documentation creation a simple task in your repository's /doc directory. Running site generation and hosting is build into github, so no GitHub action or other CI/CD pipeline needed. Lacks good tooling for multi-version documentation
  • Maven sites: a good option when Java is your language. Tightly coupled to the build process it produces full reporting and JavaDoc. Can be a pain to setup
  • Read the docs: Great destination for OpenSource documentation or your corporate documentation if the build server can reach it. Uses the MKDocs rendering engine
  • and many, did I say many more

I found the tools quite impressive and somehow wanting at the same time. So taking a step back, it is worth to look at requirements

Will work for me, might not work for you

A good documentation system is like squaring a circle. Requirements most likely will conflict. Here is my list:

  • File system based, so it can be versioned by Git and build by any CI/CD system including GitHub actions
  • containable in a container for local run (pun intended)
  • template driven approach (I like Mustache) so I can take any html layout to render
  • main navigation structure following the file system structure, DITA doesn't do that, they use XML files, Jekyll does
  • Single branch versioning. Here it gets tricky. most systems use Git branches to maintain versions of software, thus conflating "document version" with "software version". If you update / rectify content you need to jump branches and copy/paste - not an appealing
  • Markdown (with extensions) support to build visual appealing results
  • Integration of PlantUML
  • comprehensive alternate navigation options (date, tags, changed)
  • navigate to the same page for a different version of the software
  • see the version in the URL too


Since git branches isn't an option I thought to pack the version into the file name and meta data. Lets look at an example. Lets have a file dbsetup.md in the docs/database directory. It would result in the file getting rendered in all versions of the site somesite/database/[anyVersion]/dbsetup.html. In the meta data I would add:

firstVersion: 0.0.1
lastVersion: 2.7.3

For 2.7.4 onwards we would use a new file dbsetup.2-7-4.md with the respective meta data:

firstVersion: 2.7.4

The rendering engine would need to pick this up and write files into the version target directory. Something to ponder about

What do you need in your documentation?

Posted by on 09 March 2022 | Comments (0) | categories: Software


  1. No comments yet, be the first to comment