La documentation technique est un débat qui déchaîne les passions dans les différentes équipes, quelles que soient leurs spécialités depuis des décennies. Quand elle doit être écrite, on la dépriorise et quand elle est manquante dans un projet, elle retarde toutes les équipes. Je vais donc me pencher sur les problèmes de la documentation technique que j’ai pu observer durant mes expériences.

Mille et une raisons de ne pas faire de documentation

On ne va pas se mentir faire de la documentation n’est pas la partie la plus marrante de nos métiers, mais elle fait partie intégrante de celui-ci. Je pense même que pour être un bon “tech”, il ne faut pas juste savoir “pisser du code”, il faut savoir documenter et comprendre les besoins métiers entre autres. Néanmoins dans beaucoup de cas on l’omet, ou l’esquive pour de multiples raisons. Je ne pense pas qu’il y ai de bonnes raisons d’éviter la documentation, je vais donc passer en revue des excuses que j’entends trop et voir pourquoi elle ne se justifie pas.

Si le code est clair, il n’y a pas besoin de documentation.

Surement une des explications les plus courantes, en réalité elle traduit un problème plus profond. Le but de la documentation technique n’est pas d’expliquer les lignes de code mais le contexte de l’implémentation et d’en donner une vue globale pour gagner du temps et de l’efficacité.

Vous savez développer, la personne qui reprendra le code le sait aussi. Par contre ce qu’elle ne sait pas c’est le contexte dans lequel cela a été réalisé et pourquoi. Car on le sait tous, parfois on fait des choix étranges qui sont nécessaires à cause du contexte. Par exemple, pourquoi redévelopper une fonction pour faire une action, pourquoi implémenter un programme de cette façon. Il peut y avoir des raions, techniques ou politiques, mais ces raisons ne se verront pas dans le code au premier coup d’oeil.

Le code nécessite parfois de la documentation sous forme de commentaires. Nous avons tous nos petites habitudes et nos petits hacks qui peuvent complexifier la lecture du code, c’est pourquoi pour être plus efficient il est toujours préférable d’écrire une petite ligne pour l’expliquer. Il ne faut cependant pas faire d’excès de zèle et sur-commenter, avoir plus de lignes de commentaires que de code est souvent symbolique d’un problème. Prenons un exemple parlant que je vois encore souvent, les lignes de commentaires de ce type :

# Permet de récupérer l'id
function get_id():
	return this.id

Le commentaire n’apporte rien mise à part augmenter le nombre de lignes.

La documentation est donc nécessaire, quelle que soit la qualité du code

On va réduire le nombre de jours / hommes sur la documentation.

Une autre phrase que vous avez dû entendre souvent ! Car oui, beaucoup de projets informatiques finissent par avoir du retard, comme dans beaucoup d’autres domaines. Pour réduire les retards, les gestionnaires de projets ont une technique assez classique, supprimer ou réduire le temps donné aux tâches non prioritaires. Retenez par “non prioritaire”, toutes tâches n’apportant pas directement un rendement. Autant dire que cela contient souvent : l’optimisation, le refactoring et la documentation. Alors oui, ça fait économiser quelques jours hommes dans l’immédiat, mais sur le long terme cette approche n’est pas rentable. L’application va avoir un cycle de vie qui va à de nombreuses reprises avoir besoin d’être modifié, mise à jour. À chaque fois qu’une personne devra travailler dessus, elle va devoir prendre du temps pour comprendre le code et le contexte avant de pouvoir travailler. Il est rare que sur le cycle complet de vie du produit cela soit rentable.

À cela s’ajoute encore un autre point, il ne faut pas réinventer la roue, donc réutiliser le code le plus souvent possible. Si vous souhaitez que votre code soit réutilisé, un des premiers critères sera la présence de documentation et l’organisation de celui-ci. Exemple: si vous faites de l’Infra As code avec Terraform, cela va vous prendre plus de temps de séparer les éléments en modules indépendant, mais vous ou d’autres pourront les réutiliser pour divers projets.

La documentation n’est pas une tâche optionnelle à faire quand on a le temps, elle fait partie du projet et apporte de la valeur

On a tout automatisé, il n’y aura pas besoin de documentation.

Aujourd’hui avec l’agilité et l’approche DevOps il est de plus en plus courant d’avoir des projets très matures sur l’automatisation comme l’utilisation du déploiement continue, d’infrastructure cloud automatisée et j’en passe. Avec tout ça, on est parfois tenté de se dire qu’il n’est pas nécessaire de faire de la documentation.

Automatiser les choses ne veut pas dire perdre la maîtrise, je pense qu’il est important de comprendre les tâches faites par notre industrialisation et de savoir les faire sans. Cela permet de corriger les bugs et optimiser vos solutions, sans cela en cas de problème vous serez bloqués. Petite anecdote, j’ai déjà entendu un administrateur à qui l’équipe sécurité à demandé de mettre à jour OpenSSL en urgence, Il n’a pas compris où OpenSSL se trouvait ni comment le mettre à jour car en réalité, il récupère qu’une image Docker sur le DockerHub. Je pense que cela montre bien pourquoi il est important d’avoir conscience de la partie invisible de l’iceberg.

Savoir ce que l’automatisation fait cela fait partie de la documentation. Six mois après la mise en production, il y a peu de chance de se rappeler les spécificités du système. La documentation vous remettra dans les rails facilement, surtout sur les infrastructures actuelles qui sont de plus en plus complexes.

La documentation est nécessaire, quelle que soit votre maturité sur l’automatisation

Si je documente mon travail, on pourra me licencier.

Ça va peut-être en choquer certains, mais j’ai déjà entendu cette phrase plusieurs fois. D’ailleurs, c’est souvent ces mêmes personnes qui veulent limiter l’automatisation pour cette raison. Bref, je ne leur jette pas la pierre, je peux comprendre qu’on ai peur de perdre son emploi. Il ne faut cependant pas se leurrer.D’expérience le fait qu’il n’y ait pas de documentation n’empêchera jamais une entreprise de procéder à des licenciements. Je pense même que ça va souvent plus détériorer la qualité et l’ambiance de travail.

Bref, ne faites pas ça, je ne pense pas que ça jouera un jour en votre faveur bien au contraire.

La documentation n’empêchera pas de vous faire virer mais ne pas en faire peut entrainer le licenciement plus rapidement.

La documentation à l’heure de l’agilité et du DevOps

On a vu différentes raisons qui sont souvent invoquées pour ne pas faire de documentation mais nous n’avons pas abordé une particularité qui me tient à coeur: la documentation à l’heure de l’agilité et du DevOps. Quand on a accéléré le déploiement des applications et des infrastructures, on a gagné pas mal de temps, mais qu’en est-il de la documentation ? Concilier les deux est pourtant important et je ne pense pas que ce soit si compliqué.

Pour gérer celle-ci à l’heure du DevOps, j’aurai tendance à conseiller les choses suivantes :

• La documentation doit faire partie du cycle de vie, donc être versionnée et tagée comme celui-ci. En général, je choisis de le stocker dans le dépôt git du code associé, ça évite de le perdre au passage.
• Les modifications doivent être accompagnées des documentations associées, si elle est faite en continu c’est plus rapide. Chaque merge request doit-être accompagnée des modifications et ajouts de documentation associés.
• Écrire la documentation doit-être un réflexe et être fait en même temps que le code comme si celle-ci en était une partie intégrante. Je déconseille de mettre juste une tâche de documentation en fin de projet, répartissez la dans les tâches techniques elle en fait pleinement partie.
• Automatiser au maximum possible, quand vous documentez des modules Terraform ou des API REST il existe des outils permettant d’automatiser une bonne partie comme les versions, les entrées / sorties, etc.
• Faites la vivre, souvent les gens ont tendance à ne plus lire et directement demander sur les chats. On a tous reçu des messages sur Slack ou autre pour nous poser des questions auxquelles les réponses étaient dans la documentation. Renvoyez ces personnes vers la documentation gentiment en leur demandant de vous recontacter si ce n’est pas assez précis, si c’est le cas, faites-la évoluer ! Car demain vous serez peut-être en vacances sur une île paradisiaque et vous ne pourrez pas répondre.
• Si vous êtes dans un contexte entièrement francophone et que vous ou l’équipe n’est pas toujours à l’aise avec l’anglais, il n’y a pas de honte, faite là en français ! L’important c’est que la documentation ne doit pas être une barrière ou une difficulté, mais une aide.
• Tout le monde doit documenter ce qu’il fait, ce n’est pas à une personne d’assumer un point aussi central et important.

Voilà les quelques points qui me semblent importants pour avoir une méthodologie de documentation efficace dans un environnement DevOps. La liste demeure néanmoins personnelle et non exhaustive.

Pour finir : RTFM

La documentation est importante, elle fait gagner du temps à vous et aux futurs techniciens. Oui, avec du reverse engineering, vous pouvez vous en sortir, ça m’est arrivé de tomber sur des programmes obscurs que j’ai dû comprendre à coup de strace, nc ou encore tcpdump, mais c’est chronophage et pas efficace sur le long terme. N’ayez pas non plus peur de répondre “Read The Fucking Manual” à une personne, afin de lui donner le réflexe de lire la documentation pour qu’il gagne en autonomie.

Étant consultant, mon but n’est pas de rester ad vitam aeternam chez le client, mais de l’aider à prendre la main pour n’avoir avant mon départ, qu’à lui donner le manuel et les clés de son nouveau système. Pour que ce client et ces équipes puissent s’émanciper, la documentation est vitale.

Si vous ne le faites pas pour vous, faites-le pour la personne qui viendra après vous. Vous pouvez peut-être lui sauver des semaines d’un travail peu intéressant et long.