La doc va bien, ne t’en fais pas

Fri, 26 Apr 2024 17:55:09 +0000

Conférence : Devoxx France 2024
Date : 17 avril 2024
Speakers : Damien Lucas (OnePoint)
Format : Conférence (45 mn)
Slides : https://dlucasd.github.io/la-doc-va-bien-ne-t-en-fais-pas/devoxx/#/
Vidéo Youtube : https://www.youtube.com/watch?v=zQ0A75HqFuA
Repo GitHub : https://github.com/dlucasd/la-doc-va-bien-ne-t-en-fais-pas

La documentation, sujet atemporel. Travaillant sur des projets en TMA, Damien faisait le constat suivant : d’un projet à l’autre, la structure, l’organisation et le niveau d’informations de la documentation diffèrent. De temps à autres, Damien assistait à des réunions visant à restructurer la documentation. Chaque participant a sa vision. Trouver un consensus n’est pas facile.
Damien s’est ainsi demandé s’il n’existait pas clé en main un template de rédaction de la documentation, si possible Open Source et reconnu par la communauté des dévs et architectes.

Au cours de ses recherches, il est tombé sur le framework arc42 créé en 2005 par 2 allemands : Gernot Starke et Peter Hruschka. Ce template se focalise sur l’ architecture des logiciels et des systèmes. Plusieurs formats sources sont possibles en téléchargement depuis la page https://arc42.org/download : asciidoc, markdown, latex, Word, Confluence, html, Doxygen, IBM Rhapsody … Voici par exemple le template arc42 pour Word : arc42-template-FR-withhelp-docx.zip

Damien a une préférence pour l’asciidoc qui permet d’avoir une approche docs-as-code : on peut le commiter dans un repository git puis générer un document au format souhaité (ex : PDF)

Les templates arc42 au format asciidoc (extension .adoc) sont disponibles sur le repo GitHub arc42-template: une dizaine de langues est supportée dont le français.

Ce template nous guide et nous pose les bonnes questions :

Contenu : que faut-il documenter ?
Motivation : pourquoi documenter et pour qui ?
Représentation : comment documenter ? Faut-il préférer un diagramme ou une liste à puce ?

Arc42 propose de documenter une application en 12 chapitres. Chaque chapitre est lui-même généralement composé de 3 sous-parties.
Dans de ce talk, Damien s’appuie sur un projet fictif pour illustrer chacun des 12 chapitres. Ce projet consiste à développer une application de billetterie pour les JO. Il en profitera pour nous présenter des outils de génération de diagrammes (PlantUML et Mermaid), des outils de modélisation (C4 et Structurizr) et des outils de génération de documentation (avec CLI et donc intégrable à la CI).

Plantuml on Java & Moi

La doc va bien, ne t’en fais pas