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.
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.
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.