Make documentation great again (1/2)

The most basic example of "Documentation as Code" is the traditional README.md file at the root of every project. Ideally, this file contains the minimal documentation for the project, installation instructions, and perhaps a description of the main features.

In reality, this file is too often neglected and rarely kept up to date. And that’s a shame! Since it’s part of your project, it’s versioned, and there’s no need to open a new tool to change the documentation (we see you, Confluence or SharePoint!).

And you’ve probably noticed that by default, it’s a .md file, which means it’s written in Markdown, a language that allows you to format text using tags (define a title, bold text, etc.).

The huge advantage: a human can read it without feeling like they’re reading code (useful for non-technical stakeholders of a project), but your IDE or GitHub can also display it as a nicely presented HTML page. Very convenient for making your documentation available to the public.

But sometimes documentation goes beyond simple text, and we need to display tables, which are poorly handled in Markdown. Another disadvantage of Markdown: it doesn’t provide semantic meaning to the generated content, which means you have to manually insert HTML to benefit from CSS classes or specific tags.

To meet different emerging needs, "flavors" of Markdown have appeared. So many different versions, different interpreters…​ and in the end, we lost the promised universal language.

Enter AsciiDoc. Like Markdown, it’s a language of tags that is quite simple and readable by a human even without interpretation. But it offers tags to display a much wider range of data types than basic Markdown.

Another advantage is the ability to include a file in an AsciiDoc text. For example, you can display code present in a project file and see that code snippet updated in the documentation every time the source file is modified.

For the more curious, Asciidoctor provides a detailed comparison between AsciiDoc and Markdown.

As I mentioned last year in a post, I have the pleasure of supervising students in a series of courses on Blockchain technologies. In these courses, a significant emphasis is placed on practical work, and yes, we even talk about cheese…​

The lab supports are regularly updated, including during the sessions when students notice errors or need more details. The process of making the updated version available would be much slower if the support were written in Word, for example, which would require manual export to PDF and then sending it by email, etc.

In our case, by requesting generation in both PDF and HTML formats for the support materials, and using a simple GitLab CI job, we can make the new version of the support available to the students in just a few moments.

Okay, we’ve just seen that there is a tag language for formatting text for documentation purposes (even for writing books!), more advanced than Markdown…​ and certainly more relevant to the world of computers than LaTeX, which has other interests.

However, we still need to write this documentation, and that doesn’t solve all our problems. What if I told you that we can go further? Find out more in the next article!

Useful links: