Improving documentation publication and maintenance with AsciiDoctor

One of the main problems in the development work is the difficulty to maintain and publish documentation of a project. As any manual work, it tends to be delayed and eventually forgotten. In the User Service Team in eDreams ODIGEO, we started one year ago a process to automate as much as possible these steps.

After some research of the available options in the market, we chose AsciiDoctor due to its features and easy integration with our release process at that moment. Also, the human readability of the markup language (asciidoc) was a key factor in the decision.

We discarded the idea of including the documentation in the README of the project as for us it did not fit into the usual README structure. As the publishing platform, we decided the Confluence of the project so we could store all the release versions as well as the current one.

Key features for us

There were several features that were crucial for us when we decided to improve our documentation:

Modularization of the documentation. The documentation we had up to that moment was in a single 3000-thousand-lines file, which made it quite time-consuming to look for what was needed and to modify it while still being consistent.
AsciiDoctor gave us the possibility to split that file into several smaller ones and include all of them in the index file which is the source of the generated files.
The inclusion of source code. In order to avoid the repetition of text, the possibility to include directly some parts of the code was really helpful, especially when dealing with models of data. This way, it was also avoided an accidental omission of a change.

Code with the comments to be exported to documentation

Inclusion of source code in asciidoc file

Generated documentation

Automation of publication

Another common issue with the documentation is the delay in the publication, so the idea of including that in the normal release process seemed like a good idea.

The asciidoc files are updated as part of the development cycle when the feature requires it. Our project is based in maven and AsciiDoctor includes a maven plugin which compiles the asciidoc files and builds a PDF/HTML with the result.

The solution we implemented was to create a new maven profile which triggers this plugin. That profile is activated when compiling in Jenkins in the production forks. When the compilation ends, Jenkins sends the resulting files to the Confluence page that contains all the documents of every release.