Technology constraints

For my own purpose, I have a couple of high-level requirements for the documentation technology stack.

The source format must 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 must be simple tools for WYSIWYG editing, to focus on writing rather than markup.

Obvious choices are Markdown and Asciidoc. Robust standards such as DocBook and DITA are XML-based, and require dedicated editors. They also require a lot more learning, to be able to use them well.

It must be possible to generate a static website from the documentation.

I want to generate a single documentation site, possibly from multiple repositories.

Previous requirements:

In a previous assignment, we were developing several tools, and were looking for a way to create a single documentation website with overarching background information.

So I was looking at ways to combine multiple repositories, and maintain documentation for multiple versions.

In my current context, these requirements have become nice to haves.

Technology choices

Markdown for text

I have chosen Markdown as the basis for my notes, as the most popular and widespread simple plain-text format right now.

Although the lack of standardisation of Markdown leads to a variety of Markdown flavours, each trying to add features in their own way, in practice I found it is possible for me to have a sufficient level of compatibility across tools.

Previously, I used Asciidoc, with Antora as an opinionated website generator. In practice, however, having to switch or convert between Markdown for private notes, and Asciidoc for a public site, created friction.

It is also the reason I have included editing tools in the system context for my documentation system.

Mermaid and PlantUML for diagrams

Just as Markdown is a popular format, Mermaid has become a popular format to describe various types of diagrams in plain text. It is included in many tools by default, reducing the friction to use it even further.

However, not all types of diagrams are supported (or supported well) in Mermaid, so I still want to use PlantUML as a plain text format too.

The main drawback of diagrams as code is the lack of control over the resulting layout. In practice, however, the result is usually good enough.