Make documentation great again (1/2)

L’exemple le plus trivial de "Documentation as Code" est le traditionnel fichier README.md à la racine de tous les projets. Dans l’idéal, ce fichier contient la documentation minimale du projet, les instructions d’installation et peut-être même un descriptif des principales fonctionnalités.

Dans les faits, ce fichier est bien trop souvent négligé et rarement remis à jour. Et c’est bien dommage ! Comme il fait partie de votre projet, il est versionné et il n’y a pas besoin d’ouvrir un nouvel outil pour changer la documentation (Confluence ou SharePoint, on vous voit !).

Et puis vous avez remarqué, par défaut, c’est un fichier .md, autrement dit en Markdown, un langage qui permet de formater du texte via des balises (définir un titre, mettre en gras, etc.).

L’énorme avantage : un humain peut le lire sans avoir le sentiment de lire du code (utile pour les parties prenantes non techniques d’un projet), mais en plus votre IDE ou GitHub peuvent l’afficher comme une page HTML bien présentée. Très pratique pour mettre à disposition du public votre documentation.

Mais parfois la documentation dépasse le simple texte et on a besoin d’afficher des tableaux : ils sont très mal gérés en Markdown. Un autre désavantage du Markdown : il ne donne pas de sens (sémantique) au contenu généré, autrement dit il faut insérer manuellement du HTML pour bénéficier de classes CSS ou de balises spécifiques.

Pour répondre à différents besoins qui ont émergé, des "flavors" de Markdown sont apparus. Autant de versions différentes, d’interpréteurs différents …​ et à la fin on a perdu le langage universel promis.

C’est alors qu’intervient l’AsciiDoc. Comme le Markdown, c’est un langage de balises assez simple et lisible par un humain sans même être interprété. Mais il propose des balises pour afficher bien plus de types de données que le Markdown de base.

Un autre avantage est la capacité à faire des "includes" d’un fichier dans un texte AsciiDoc. Par exemple, il est possible d’afficher le code présent dans un fichier du projet, et de voir ce morceau de code mis à jour dans la documentation à chaque modification du fichier source.

Pour les plus curieux, Asciidoctor propose une comparaison poussée entre Asciidoc et Markdown.

Je l’évoquais l’an dernier dans un post, j’ai le plaisir d’encadrer des étudiants sur une série de cours autour des technologies Blockchain. Dans le cadre de ces cours, une grande place est laissée à la pratique, et même que l’on y parle de fromage…​

Les supports des TP sont régulièrement mis à jour, y compris pendant les séances lorsque les étudiants remarquent des erreurs ou ont besoin de plus de détails. Opération de mise à disposition qui serait bien plus lente dans le cadre d’un support rédigé sous Word par exemple, qu’il faudrait exporter en PDF manuellement, puis envoyer par mail, etc.

Dans notre cas, en demandant une génération en PDF et en HTML du support, et via un simple job de Gitlab CI, nous mettons à disposition en quelques instants la nouvelle version du support aux étudiants.

OK, nous venons de voir qu’il existe un langage de balises pour formater du texte à but de documentation (voire de rédaction de livres !), plus évolués que Markdown …​ et surtout que LaTeX qui a d’autres intérêts, plus éloignés du monde de l’informatique.

Pour autant, il faut encore rédiger cette documentation, cela ne résout pas tous nos problèmes. Et si je vous disais que l’on peut aller plus loin ? La suite dans le prochain article !

Liens utiles :