Documentation format

Development Documentation
12

I think before we jump to conclusions which format is best, it’s important to think about what the outcomes should be.

The goals would be:

  • extremely simple to do small improvements
  • quick feedback loop
  • no maintenance of the tooling from our side (we already have a big wagon to push by reinventing devops)

From the top of my mind, here are the desired properties of a good documentation tooling:

  1. live preview of the documentation as I’m changing it
  2. good editor integration (live preview, syntax highlighting)
  3. extremely simple way to render documentation into multiple pages with a search
  4. good conversion story from docbook
  5. active community supporting the tooling infrastructure
  6. good support of references, especially cross-project

The reason I chose asciidoc over markdown was since (4) is basically impossible as markdown support very basic markup and because of (5) - everyone at writethedocs conference said to avoid markdown. There’s also not a good story of (6) for markdown, which is needed for linking between nixos and nix documentation.

So we’re using https://antora.org/ for generating documentation across projects, which uses https://asciidoctor.org/ under the hood to render asciidoc.

8 Likes