Pourquoi écrivez-vous de si mauvaises documentations, alors que votre code est de bonne qualité ?

L’architecture et le code de nos projets, quand nous pouvons faire du bon travail :

Les documentations de ces mêmes projets :

Nos documentations sont sans ambition. Nous ne faisons pas d’effort pour les structurer ni les rédiger. Elles sont très vite obsolètes et abandonnées, non maintenues et inutiles. Voire contreproductives.

Pourquoi créer de la documentation (de qualité) ?

Déjà, je n’ai pas dit « écrire de la doc » !
Tout comme développer une application inclut d’autres tâches que la seule écriture du code, créer de la documentation est bien plus vaste que la seule écriture du texte !

Tout d’abord : la documentation ou, plutôt, les documentations, à quoi ça sert ?

Et bien, en me limitant aux premières idées qui me viennent à l’esprit :

• Expliquer à des collègues comment mettre en place une solution : comment configurer une brique de leur projet, comment appeler notre API…
• Éclaircir pourquoi nous avons pris une décision. Un objectif est d’aider nos collègues, dans deux ans, à comprendre ce choix. Sans cela, ils et elles devront reproduire toute notre réflexion pour savoir si la réponse retenue est toujours adaptée !
• Assez semblable : conserver suffisamment d’informations pour faciliter un changement d’avis éclairé, dans trois ans, en retrouvant les raisons de notre démarche actuelle.
• Convaincre. Qu’une approche est la plus appropriée, par exemple. Y compris en asynchrone ou plusieurs mois après.
• Transmettre comment fonctionne une solution, peut-être complexe, que nous avons développée. Pas les détails, qui se trouvent dans le code mieux qu’ailleurs, mais la vision globale. Par exemple, un schéma d’architecture, qui indique comment une plateforme microservices est structurée, comment ses composants communiquent¹.

Ce ne sont qu’une partie des multiples intérêts des documentations. Je me suis d’ailleurs arrêté aux documentations internes à une entreprise ou à une équipe et je n’ai pas abordé, ci-dessus, les documentations externes, celles qui visent des clients ou des utilisateurs.

L’envie et le temps de travailler aux documentations

Il y a bien longtemps, en SSII sur un projet au forfait, un manager m’a dit², en parlant de qualité de code :

La qualité, on s’en fout ;
Dans six mois, c’est plus nous.

À l’inverse, le but de la documentation est d’aider notre « moi » du futur.

Produire de la documentation utile prend du temps. Pour les développeurs et développeuses, bien sûr. Mais aussi pour l’ensemble de l’équipe projet. C’est un investissement.

Parfois, si nos documentations n’apportent aucune valeur, c’est parce que nous³ n’en avons rien à faire, parce que nous ne sommes pas intéressés par faire du bon boulot. Ou, peut-être, parce que nous croyons que notre métier n’est que coder… Mais je suis persuadé que ce n’est pas toujours le cas !

Nous construisons nos documentations tout au long de la vie du projet :

• Pendant la conception, nous faisons des choix (pourquoi ?) et créons des choses (architecture). Je crois que réfléchir avant de coder est judicieux, tout comme documenter le fruit de ces réflexions.
• Pendant l’implémentation : là aussi, nous faisons des choix. Nous documentons certaines décisions sous forme de code, mais d’autres nécessitent une vue de plus haut niveau.
• Avant, pendant et après, vous travaillez votre manuel. Pour un logiciel grand public ou pour une bibliothèque ou une API appelée par une équipe technique, vos utilisateurs et utilisatrices ont besoin de comprendre comment exploiter votre produit !

Nous devrions aussi documenter pendant des moments où ce n’est pas notre priorité !
Par exemple, pendant un incident : prenons des notes (un comportement constaté, une tentative de correction, son effet) et réalisons des captures d’écrans ! Une fois l’évènement terminé, elles seront indispensables pour rédiger un post-mortem⁴, apprendre, écrire une documentation qui expliquera comment régler ce problème, ou, mieux une story pour éviter qu’il ne se reproduise !

Enfin, nous refactorisons, retouchons, améliorons, dé-dupliquons, optimisons le code de nos applications. On parle même de code legacy et de dette technique à rembourser !
Pourquoi n’accordons-nous pas autant d’attention à nos documentations ?
Nous devrions les faire évoluer, elles aussi ! En incluant des retours des lecteurs et lectrices, en prenant en compte les difficultés qu’elles rencontrent. Sans oublier les nouveautés du logiciel ou de son architecture !

Documentations, publics, idées, processus et méthodes

Pour partager du savoir, la première étape est de définir notre public⁵. À qui nous adressons-nous ?
Nous saurons ainsi quel langage employer, quelles connaissances notre lectorat a déjà, sur lesquelles nous pouvons nous appuyer.
Quand vous programmez, vous ne mettez pas tout votre code en vrac dans un fichier nommé utils.php, n’est-ce pas ? Chaque arrivant sur le projet se demanderait s’il doit ou non le parcourir et ne penserait jamais à l’ouvrir pour y trouver la portion de code métier qui l’intéresse !
Et bien, identifiez votre public cible, tout en haut de chacun de vos documents ! Si quelqu’un doit lire pendant plusieurs minutes pour savoir si une page lui est ou non adressée, c’est une perte de temps inacceptable !

Question suivante : avec quoi le public doit-il repartir ?
Nous n’écrivons pas une documentation uniquement parce que nous devons écrire une documentation !
Que vont apprendre vos lecteurs ? À laquelle de leurs difficultés va répondre cette lecture ? Notez-le, explicitement !
C’est comme implémenter une fonctionnalité : on ne code pas pour coder, notre job n’est pas écrire du code. Notre rôle est d’apporter de la valeur à l’utilisateur et à notre employeur. Pour cela, nous implémentons une fonctionnalité dans un logiciel, dans un produit. Mais ce n’est pas la finalité !

Au tour du plan : on y place nos idées, les grandes lignes de notre documentation. Et, surtout, on les ordonne jusqu’à arriver à un tout cohérent qui présente ses informations dans un ordre logique, pour que le lecteur sache les comprendre et les appliquer.
En développement, pensez à la phase d’architecture : on réfléchit à la structure d’un projet, à son découpage en services et classes métiers, à la modélisation de son stockage, au schéma d’appels des microservices… C’est une étape critique qui conditionne toute la réalisation, donc on la mène souvent à plusieurs, avec des moments devant un tableau blanc.
Pourquoi, donc, ne pas faire pareil pour une documentation ? Pourquoi ne pas passer quelques heures à créer son plan et élaborer ses principales idées et leur organisation, en pair ?

Ensuite, de la même façon qu’on code en pair, est-ce qu’on peut écrire en pair ? Voire en mob ?
Pourquoi pas ? Si vous avez l’habitude de pair-programmer, si vous estimez que ça vous rend plus efficace, que cela vous aide à produire du code de meilleure qualité et à mieux répondre aux attentes de votre entreprise et de ses clients… Pourquoi ne pas faire pareil pour une documentation ?

Nous suivons le pourcentage de code-coverage de nos tests automatisés, nous validons en TDD que notre implémentation répond aux différents cas d’usage identifiés.
Ne devrions-nous pas, régulièrement, nous demander si la doc que nous rédigeons répond (bien) aux problématiques de notre public ?
Certes, tester automatiquement qu’une documentation répond à ces attentes n’est pas évident. Par contre, la faire lire par un membre de notre public cible, c’est possible : demandez ! Et si nous considérons que la documentation est importante, nous trouverons le temps. Sinon, pourquoi l’écrire, pourquoi l’exiger ?

Enfin, nous faisons une démo de chaque nouvelle fonctionnalité à nos collègues… Nous pourrions faire pareil pour la doc !
Cette démo montre à toute l’entreprise ce qui existe dans notre produit, ce que nous pouvons partager à nos clients… Et bien, pour la documentation, pareil : une démo permet de savoir qu’une nouvelle documentation existe et peut être suivie et partagée !

Nous mettons en place des processus, des méthodes, des habitudes de travail autour du développement de fonctionnalités et de l’écriture de code. Faisons pareil pour l’écriture de docs !

La forme : des principes et des outils

Votre fil directeur doit être votre public cible et ce avec quoi il doit repartir.

Dès le titre ! C’est lui qui conditionne si on va cliquer sur votre page dans l’arborescence des docs ou dans les résultats d’un moteur de recherche.
Pour une documentation rédigée par un DevOps voulant aider des développeurs à gérer la scalabilité et l’élasticité d’un projet, le titre « reconfigurer le HPA » ne va pas marcher ! Je parie déjà que le terme « HorizontalPodAutoscaler » entier, écrit dans les fichiers YAML du projet, ne sera pas reconnu… Donc l’abréviation « HPA », aucune chance !
Vous devez reformuler ce titre. Adaptez-le à votre public cible et à ce qu’il souhaite. Par exemple : « Comment paramétrer le scaling de votre projet pour tenir un pic de charge ». Un développeur veut que son projet tienne la charge, qu’il scale. Il ne veut pas configurer un HPA, même si c’est le moyen d’arriver à son objectif.
Quand vous codez, vous réfléchissez aux noms de dossiers, fichiers, namespaces, classes et méthodes ? Et bien, pour une documentation, réfléchissez à l’endroit où la ranger et à son titre !

Quand vous programmez, votre IDE souligne en rouge les fautes de syntaxe, les noms de fonctions erronés, les paramètres inversés.
Et bien, des outils automatisés existent aussi pour le français. Le correcteur d’orthographe et de grammaire de Microsoft Word ou de Google Docs, peut-être ? Ou, mieux et que je recommande vivement si vous écrivez souvent : le logiciel Antidote est d’un très grand soutien pour certains de mes textes !

Dans votre chaine d’intégration continue, un procédé calcule la complexité cyclomatique de votre code et vous alerte si — je simplifie — vous imbriquez trop de if. Plus le code est difficile à appréhender et à maintenir, plus il augmente le risque de bugs.
Et bien, pareil en français ! Antidote vous aide à identifier les phrases trop longues, les passages trop complexes ! Il incorpore même des algorithmes qui assignent un score de lisibilité à votre texte, ou indiquent combien d’années d’études sont requises pour le comprendre.

Et puis, ces trucs qu’on répète, ces dogmes qu’on applique sans toujours bien les saisir… Vous savez, des affirmations comme « les goto c’est mal et interdit » ?
Et bien, si vous aviez peur de vous ennuyer en changeant de langage : ça existe aussi en français ! Par exemple, « les mots en -ment⁶ mentent ! »
Aussi, évitez la voix passive, qui n’implique personne et n’aide ni l’auteur ni le lecteur à se sentir concernés par un texte !

J’en viens aux revues : une fois le code écrit, vous ouvrez une pull-request, vos collègues relisent ce que vous avez soumis, critiquent, suggèrent des améliorations.
Et bien, faites pareil pour votre documentation !
Une revue peut avoir deux objectifs et être approchée de deux manières différentes. Elle peut se concentrer sur un niveau de précision assez fin (les noms de variables / le choix des synonymes ; la position des accolades / les fautes d’orthographe) ou plus global (l’architecture du code et des classes / le plan et l’organisation des idées et leur adéquation pour le public cible).
Pour le code comme pour le français, la première approche peut être partiellement automatisée et ne mérite pas d’y passer trop de temps en revue manuelle… Et la seconde devrait avoir lieu avant de coder / écrire !

Enfin, et j’ai volontairement gardé ce point pour la fin parce que ce n’est pas le cœur de cet article : quelle langue utiliser ? Votre entreprise a-t-elle décidé que toutes vos documentations seraient en anglais, en français ?
Beaucoup, parfois par manque de pratique, ont du mal à structurer leurs pensées, à les écrire et à les rendre accessibles dans leur langue maternelle… Mais alors, dans leur seconde ou troisième ?
Pour certaines personnes, je recommande de réfléchir en français, puis de rédiger en anglais. Ou même d’écrire en français puis de traduire en anglais. Certains traducteurs automatiques (j’utilise souvent DeepL) font du très bon boulot, meilleur qu’une partie d’entre nous !
Toutefois : vous avez appris PHP, Go, Rust, ou n’importe quel autre langage avec lequel vous bossez au quotidien, non ? Et bien, apprenez aussi le langage avec lequel vous écrivez ! Bien sûr, c’est du travail et ça prend du temps. Et ça fait partie de votre métier !

Conclusion

Une documentation mal foutue, quelle que soit la raison pour laquelle elle est mauvaise, est inutile. Elle ne sert à rien. Pire même, elle dégrade votre qualité de vie, l’expérience de vos utilisateurs et l’opinion que vos clients ont de vous et de votre produit !

Pourtant, concevoir, écrire, produire et maintenir une bonne documentation est possible !
Comme créer du code de qualité, c’est du travail ! Et comme pour le code, des processus, des outils et des méthodes peuvent vous aider… Si vous en avez la volonté !

Bien sûr, vous devez pour cela avoir envie d’une documentation de qualité et être prêt à fournir l’effort nécessaire ! À votre niveau et, encore plus, au niveau de votre management et de l’entreprise !

C’est donc à vous, chaque jour, d’exiger de la documentation. De la lire. D’essayer de la comprendre. De signaler les parties qui sont claires et celles qui ne le sont pas. De demander à vos collègues ou fournisseurs de les améliorer. Et aussi, c’est à vous d’enrichir les documentations existantes⁷.

Faire un effort de rédaction, apprendre à mieux écrire, vous servira plus largement que juste pour la doc.
En effet, tous les jours, vous écrivez ! Sur Slack, par exemple, pour communiquer avec vos collègues. En travaillant à distance une partie du temps, peut-être en asynchrone, savoir exposer vos idées clairement et par écrit n’est plus optionnel !

Pour découvrir comment font d’autres entreprises, le style qu’elles ont retenu, ou parcourir des sources qui vous aideront peut-être à trouver le vôtre, voici quelques lectures, en anglais :

• Chez Monzo : Our tone of voice
• Welcome to the Mailchimp Content Style Guide
• Chez Google : Technical Writing Courses

Source de l’illustration de cet article : Mitchell Luo sur Unsplash