Replace your wiki with a documentation site
No matter what your IT project is, there will always be a need to store some documentation. The choice to use a wiki is quite common in the corporate world.
Let’s talk about you, developer on one of these programs, is documentation of your different projects managed by an easily accessible and editable wiki?
If you look at the content of this wiki, you will probably find:
- Pages with sections who
still need documentation
, - Pages with incorrect information,
- Deprecated pages,
- Pages only useful for one team or another,
- Pages with documentation on a feature still in development.
So you wonder how to make it easier for people working on different projects.
At this point, the principle of documentation as code
seems to be the solution to your needs.
You embark on the adventure of documentation as code
Seeing the documentation as code as the sources of the program is interesting. You want to replace your current wiki with a project dedicated to documentation, and allowing you to make code review
on these changes. But that only corrects part of the problem, you only replaced wiki pages with files written in another format like:
Due to its simple and accessible syntax, Markdown
is one of the most popular formats, especially on sites like github or gitlab, but it is too simple for further documentation.
Asciidoc
is more interesting, allowing to be more expressive with your documentation. The associated tool Asciidoctor provides useful features as well as integrations such as diagram generation with plantuml.
You therefore choose to write the Asciidoctor documentation in each of your projects. This allows you to deliver the documentation at the same time as the associated code.
Even if your program consists of a set of projects, each with its own documentation, you want to keep a single site to access them.
The people behind Asciidoctor have recently released an aggregated documentation site generator: Antora in a stable version (1.0.0
) to the open-source community.
You create your new documentation site with Antora / Asciidoctor
A site generated by Antora is composed of three elements:
- Your projects that contain their documentation,
- The playbook that configures the generation of the documentation site,
- A UI that defines the visuals of your site (the default one will be appropriate).
To be used by Antora, a project must respect a file structure
./docs
├── antora.yml
└── modules
└── ROOT
├── _attributes.adoc
├── nav.adoc
└── pages
├── _attributes.adoc
└── index.adoc
You set up documentation as code on your projects
So you apply yourself to put it up on:
- Your APIs (api A, api B, api C)
- Your tools (build tools),
- Your development guide (guidelines).
The documentation in Asciidoctor
format is available in the docs
folder.
It is not necessary to use this tree for
guideline
, which is only a documentation project.
You are preparing to generate your documentation site
So you create a specific project to store the playbook.
The content of the playbook site.yml
defines:
- the related information to the site itself via site:
- the definition of content via
content:
- the theme of the site via
ui:
- The build folder via
output:
The official documentation does not refer to it because it is a development still experimental but you set up the navigation bar to add the useful links via a header-content.hbs
file in supplemental-ui/partials/
.
Other template files are available for replacement in Antora Default UI.
You generate and deploy your new documentation site
You can install antora via this guide or use the docker image via the
docker run -v `pwd` command: / antora --rm antora / antora --stacktrace site.yml
(where site.yml is the playbook)
The playbook defines the docs
folder to make your new documentation site available.
For example, to make it accessible on Github, you deploy it via the Github Pages of your docssite
project.
The platform will automatically expose the contents of the /docs
folder to https://rlespinasse.github.io/docssite.
You make others benefit from the new documentation site
From now on, people working on the program will be able to add, create, and maintain documentation of each project very easily. Your new documentation site gives the access to all these pages.
The site docs.antora.org uses the Antora
project itself.
Thanks to Aurélien Allienne, Antoine Méausoone, Tanguy Baudrin, and Tony Proum for reviewing the article.
Thanks to Aurélien Allienne, Guillaume Mantopoulos for the review of the translation from french to english of this article.
Originally published at lemag.sfeir.com in french.