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

By Date: March 2022

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

Read more

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