Documentation as code
Antora allows us to manage our documentation as code, which allow us to build our website the same way as we would build a software, store the code in a version control system and build/publish our documentation website using the same CI/CD principles as used for our softwares or our infrastructures.
Asciidoc is a lightweight markup language, similar to Markdown but offers more possibilites and more flexibility. It is higly configurable and allows to write documentation, articles, web pages, etc.
Integration with Github
The website for our documentation can be automatically built and published on Github Pages using Github Actions.
Highly customizable appearance
The appearance of the website is externalized in an independant project and packaged as UI bundle. It can be highly adapted to ones needs and be can reused over multiple documentation projects.
We follow the Divio documentation structure to organize the documentation of this project, which is written in Asciidoc and built using Antora
In short, we break up the global documentation of the project in 4 parts, each of which being useful at a different time in the understanding or usage of the project:
tutorials focusing on the learning
how-to guides focusing on solving specific problems
reference guides focusing on giving information
explanation focusing on offering a better understanding
There are overlaps between those elements, but respecting this separation prevents us from building a confused (and confusing) documentation.
To get a better overview of the Divio documentation structure, you can watch this interesting presentation by Daniele Procida
This UI bundle is linked to in the
antora-playbook.yml of the documentation project and is dynamically pulled and loaded to render the resulting website during the buid phase.
There is a dedicated page that explains how to write and contribute to documentation.