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

Contenders

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

Versioning

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?