Technology choices
Main considerations
For my own purpose, I have a couple of high-level requirements for the documentation technology stack.
- The source format should be suitable for standard version control.
-
This forces it to be a plain-text markup language, stored in files. It excludes Office tools, online document editors, and database-based content management systems.
- There should be simple tools for simple WYSIWYG editing, to focus on writing rather than markup.
-
Obvious choices are Markdown and Asciidoc. Robust standards like DocBook and DITA are XML-based, and require particular editors. They also require a lot more learning to be able to use them well.
- It should be possible to generate a static website from the documentation.
-
I want to generate a single documentation site that pulls sources from multiple repositories. I also want to be able to offer documentation for different versions.
Tools and technologies
- Asciidoc and Antora as basis
-
The content sources and website generator are interlinked via their support of a common markup language, format and organisation of files.
- PlantUML and Kroki for diagrams as text
-
Diagrams are as much as possible written via plain text, using diagram standards, so they can follow the same docs as code workflows.
Elements of the documentation system
To expand on the documentation system overview:
