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.
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 pulling sources from multiple repositories into a single site. I also want to be able to offer documentation for different versions.
- 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.
To expand on the documentation system overview: