Lecture 5 minutes

Lors de l’édition 2020 du Forum PHP qui s’est déroulée en ligne, j’ai participé à une conférence captivante. Dès le début, j'ai été captivé par Samuel Rozé ! Il nous a présenté, à un rythme effréné, énormément de points d'intérêt tournant autour de la documentation.

DISCLAIMER : Cet article est le fruit de mon interprétation de la conférence de Samuel. Je vous invite vivement à aller la visionner !

Rappels

Samuel Rozé a donc abordé la documentation. Avant toute chose, il faut en rappeler les intérêts (non exhaustifs):

😘

• Réduction de la dette technique : celle-ci étant souvent liée à un manque de contexte.
• Nouveaux arrivants : il faut leur transmettre l'information.
• Amélioration des échanges : en réduisant le nombre d'incompréhensions et en précisant certains termes dans la documentation.
• etc

... mais très justement, l'expert rappelle aussi à la dure réalité de la documentation traditionnelle :

🤯

• On ne sait pas comment trouver l'information : soit notre documentation est incomplète, soit elle est trop exhaustive et illisible.
• Les documentations souffrent souvent de trop peu de mises à jour.
• Bon sang : c'est ennuyeux à lire !

La documentation “vivante”

Après ces constats, il est temps d'apporter la notion de "Documentation vivante" comme une piste de solution basée sur 4 grands principes :

• Elle doit être toujours à jour.
• Elle doit être simple à lire et maintenir.
• Elle doit être collaborative.
• Elle doit contenir des choses utiles.

Que de beaux principes, mais comment réaliser tout ça ? Samuel nous donne des pistes intéressantes !

Tout d'abord, il est important de noter la différence entre la connaissance générique (liée au framework par exemple) et la connaissance spécifique (liée au métier). Samuel conseille de se focaliser sur la partie spécifique. En effet, le générique est vraisemblablement déjà documenté "quelque part" ou évident (tout technicien qui se respecte saura lancer "composer install" par exemple).

Mais comment s'y prendre ?

Pour rédiger la documentation, il faut du temps, beaucoup de temps, et probablement encore plus pour la mettre à jour. A cela, Samuel répond : Non. Votre documentation existe déjà !

En effet, il nous explique que dans la plupart des cas, la documentation existe sous une forme peut être incomplète ou pas tout à fait compréhensible, mais elle existe.

Extraire la documentation du code

Pour introduire cela, il faut s'arrêter sur la “source of truth", ou la "source de vérité". Concrètement, cette source est la base de notre documentation. Dans la plupart des cas, dans nos métiers, il s'agit simplement... du code. Et ce code contient effectivement énormément d'informations.

Quelques pistes pour trouver des informations dans le code :

• Les messages de commit : il s'agit simplement de détailler ce qu'il y a dans ce code, ce qu'il fait et comment. Il suffira ensuite de les parcourir pour générer de la documentation.
• Les noms de branche : là aussi, en respectant des conventions, il est possible, par exemple, de générer un CHANGELOG, en le couplant aux messages de commit.
• Les commentaires dans le code (la PHPDoc par exemple) peuvent également être étudiés.

Compléter la documentation issue du code

Nous avons donc à notre disposition une formidable base de documentation que nous n'avons plus qu'à exploiter ! Souvent cependant, cette documentation est insuffisante et il faut la compléter. Il s'agit de la "réconciliation des connaissances".

L'idée est simple :

• EXTRAIRE la donnée (depuis le commit par exemple).
• TRANSFORMER cette donnée pour la rendre lisible (Markdown, HTML, PDF, etc).
• AUGMENTER cette donnée en lui ajoutant d'autres données.

Une autre source : les tests !

Et pour cela, Samuel propose une autre source de documentation : les tests. Il insiste d’ailleurs particulièrement sur le "Behaviour Driven Development" (BDD). Pour rappel, le BDD consiste à piloter ses développements par des "comportements" ou "scénarios". L'idée générale est :

• Rédiger des scénarios lisibles par des humains et des machines.
• Faire jouer le scénario par la machine.
• Faire fonctionner (en développant) le scénario.
• Intégrer (revenir à "2.").

Samuel étaye son propos avec des exemples et, en l'occurrence, Behat ❤️.

Rédiger sa documentation

Voici d'autres façons de rédiger sa documentation pour la rendre plus vivante :

• ADR (Architecture Decision Record) : liste des décisions d'architecture essentielles (une dizaine maximum). L'un des intérêts est que (normalement) ces décisions ont été prises à plusieurs et ont laissé la parole à l'équipe projet. Elles permettent notamment à chacun de prendre du contexte avant de prendre une décision.
• Schémas : les schémas permettent de comprendre énormément de choses. Et il existe des formalismes permettant d’en générer automatiquement depuis de la documentation technique (ex: Mermaid).
• Documentation Driven Design : c'est la documentation qui a déterminé la conception de l'application.
• Linter : ces composants effectuent des vérifications sur le code sont autant de documentations. Par exemple, la validation de PSR-2 indique qu'il faut travailler ... selon les normes PSR-2.

Living documentation : à retenir

Samuel finit sur quelques conseils :

• Ne documentez que ce dont vous avez besoin.
• Identifiez les sources de connaissances (source of truth).
• Augmentez ces données, c'est LA qu'il faut écrire.
• Rédigez la bonne documentation au bon moment.

De mon côté, le point qui m'aura le plus frappé, malgré toute l'évidence de la chose, est que la documentation peut être en grande partie générée.

Merci à Samuel pour cette belle présentation !