Écris ta documentation technique bordel de merde

Bon, aujourd’hui j’ai la haine. Les trois choqués parce que j’ai mis bordel de merde dans le titre, barrez-vous tout de suite c’est mieux. Apparemment, tout le monde a décidé que la documentation technique c’était de la merde et que ça servait à rien. Je me transforme en enquêteur du dimanche à cause de ça. Ça me fait péter un plomb. Il faut qu’on en discute tous les deux.

Tu crois que j’ai le temps pour ta documentation technique ?

Le temps ? Tu me dis que tu n’as pas le temps pour ta documentation ? OK, parlons-en du temps. Tu sais combien de temps tu fais perdre à tous ceux qui passent derrière toi ? Tu sais combien de temps tu te fais perdre à toi-même ? Si tu construis une librairie ou une application, ça va potentiellement être utilisé par plein de monde. Ou au minimum par toi-même. Le temps que tu gagnes maintenant à ne pas écrire ta documentation technique, tu le fais perdre à tout le monde de façon exponentielle dans le futur. OK, prenons un exemple concret.

Il y a quelques années, j’étais dans une boite qui bossait en poussant son code sur un serveur dev et en testant directement dessus. L’enfer sur terre. Du coup, j’ai fait un environnement de travail local pour l’équipe. Concrètement, j’ai simulé la prod dans un docker-compose géant avec tous les microservices, le PostgreSQL, le Redis et même des volumes pour la data. Bref, tout le bordel pour qu’on puisse bosser tranquille. Ça marche sur ma machine. Ship it, c’est parfait comme ça.

Évidemment zéro documentation. Aucun requirement. Rien. Démerdez-vous les gens. Et ça pour plusieurs raisons. Déjà, bien sûr, la grosse flemme. Ensuite, j’ai passé du temps sur l’environnement en lui-même alors autant en gagner sur la documentation. Enfin je me suis dit que ça allait permettre à ceux qui ne connaissent pas de se familiariser avec docker-compose et comment ça fonctionne. Je suis un génie ou je suis pas génie ?

Ce qui devait arriver arriva. Très vite j’ai commencé à recevoir des mails remplis du fameux : « ça marche pas ». En particulier des nouveaux arrivants. J’ai passé mes journées à expliquer comment fonctionnait docker-compose, ces requirements et comment travailler avec dans le cadre de notre solution. J’ai pleuré du sang et j’ai fini par faire une énorme documentation. Le temps de setup complet est passé d’une journée avec moi, à plusieurs heures en autonomie. La documentation rend les gens autonomes et te permet à toi de pas être dérangé dans ton travail non plus. Le temps gagné par ton entreprise est phénoménal. Et ça marche pour tout, partout. C’est le même scénario à chaque fois. Ton argument de gagner du temps est invalide.

OK, mais je sais pas écrire ta documentation technique

Non mais on parle de documentation technique, c’est pas Shakespeare le bordel. Le seul fait que ce blog réussit à avoir du trafic prouve qu’il n’y a pas besoin d’être un écrivain pour être lu. Tout ce qu’il faut c’est du contenu qui va aider les gens. Et ta documentation technique va vraiment aider les gens.

Tu sais pas par quoi commencer ? Très simple, voilà les sections OBLIGATOIRES. Tu t’en fais un template, tu le mets dans tous tes README et les gens vont t’aimer.

• Introduction

Quelques lignes qui expliquent le pourquoi du comment de ta librairie ou de ton app. Super important pour un utilisateur qui veut juste savoir rapidement s’il pourrait utiliser ton truc. S’il n’y a même pas ça autant rien mettre c’est pareil.

• Dépendances

Quelles sont les dépendances sans lesquelles ta librairie ne peut pas tourner. Si tu ne les mets pas. ton truc marche pas. Personne va avoir la patience de chercher pourquoi ça marche pas. Et ta librairie : poubelle.

• Quick start

La suite de commande ou le bout de code qui permet d’utiliser rapidement la librairie. C’est super important pour un développeur qui veut juste faire un POC pour voir si ta librairie est viable. Sinon pareil personne aura la patience de chercher. Poubelle.

• Notes

Peut-être la partie la plus importante en fait. Ici, tu mets tous les hacks ou les choses à savoir pour n’avoir aucun problème avec la librairie. S’il y a de la dette technique, soit franc et parles-en ici.

Évidement il s’agit du strict minimum. On est au niveau zéro. On est au niveau j’ai pas envie de le faire mais je le fais quand même. Avec ce niveau de documentation, si ta librairie est bonne, tu auras des gens qui vont accepter de l’utiliser. Et faut vraiment que ton code soit parfait.

Mon code est parfait ! Pas besoin de documentation technique

C’est insupportable. Quand tu tombes sur une librairie qui a zéro documentation sur GitHub tu vas l’utiliser ? Tu vas passer ton temps à regarder dans le code, fonction par fonction, pour savoir si c’est bien codé et si ça te convient ? Non. Tu vas fermer la tab et tu vas continuer tes recherches. Pas de doc, pas de chocolat. C’est exactement pareil pour tes librairies à toi. Ton travail de demi-Dieu ne sert à rien s’il n’est pas documenté.

Pourquoi c’est si important que tu écrives un minimum de documentation sur ton travail ? Si ta librairie n’a pas de documentation technique, ta librairie n’existe pas. T’es une rock-star, ton code c’est du Mozart et ton application révolutionne le monde ? C’est con, tout le monde s’en carre le cul. Elle est où la doc Einstein ?

Mais c’est pas fini mon truc donc pas de documentation technique

Mais c’est pas une question de fini ou pas. Y’a des gens qui vont utiliser ta librairie en l’état ? Et oui, cette question inclut toi-même. Si oui alors il faut une documentation. C’est quand une librairie n’est pas finie qu’elle a le plus besoin de documentation. Explique ce qui marche. Explique ce qui marche pas. En fait explique surtout ce qui marche pas. Explique où ça en est. Les hacks et les choses à savoir pour ceux qui passent derrière toi. Des choses qu’ils vont leur faire gagner du temps.

Story time. Il y a bien longtemps dans une galaxie lointaine, très lointaine, j’ai bossé avec un produit interne. Évidemment, t’as deviné, y’avait pas de documentation. J’ai pas le choix et c’est un produit en cours de développement. Donc on est sur un grand chelem, salade tomate oignon. En plus faut ship vite. Je te passe les détails je fais ma petite API et je veux pousser une première version. Je pousse et là ça plante. Timeout dans la pipeline. Pas d’erreur. Aucune idée de ce qui se passe. Écran noir. Démerde-toi.

Immédiatement, gros git blame des familles. Je trouve le nom et le dude est pas là aujourd’hui. Bah oui, sinon c’est pas drôle. Du coup je commence à essayer un milliard de trucs. Différentes façons de faire mon API, mettre des logs partout, envoyer une API vide. Timeout, ça marche pas, et ça pendant des heures. Désespéré, je commence à regarder tout le code source du projet. Faut savoir que c’est une énorme machine à gaz le bordel. Et là je tombe sur un fichier bash caché au milieu du process de pipeline. Il retourne false s’il trouve pas une route qui s’appelle /status. Juste false. Pas de log. Pas d’erreur. False. Si j’avais su ça tout de suite ça aurait duré cinq minutes.

La documentation technique minimum c’est la documentation de la dette technique. Ne pas faire ce minimum-là est une source de perte de temps phénoménal. La flemme que tu as eu à ne pas documenter a fait perdre beaucoup d’argent à ton entreprise. Et c’est entièrement ta faute. Sans parler du fait que les autres développeurs vont te maudire. Si tu fais rentrer quelqu’un dans un terrain miné au moins donne-lui un détecteur à mine. Là, il va t’aimer fort même si tu fais de la merde. Et surtout il va revenir vivant.

T’es pas content ? Utilise pas ma librairie !

Mais j’ai pas le choix ! Tu produis une librairie interne. Comme je t’ai dit plus haut si c’était une librairie open-source je l’aurais même pas regardée ta librairie. Je l’aurais même jamais trouvée en fait.

Également la documentation tu l’écris pas que pour les autres. Comme le dit Damian Conway « La documentation est une lettre d’amour que tu écris à ton futur toi. ». Dans quelques semaines, quand tu auras tout oublié ce que tu faisais sur ce projet, tu vas te faire gagner un temps fou.

Bref. Respecte tes collègues. Envoie-leur de l’amour. Permets-leur d’être complètement autonomes. Permets-leur d’aller vite grâce à toi. Fais gagner un temps incroyable à ton entreprise. Fais gagner de l’argent à ton entreprise. Fais en sorte que tes collègues ne soient pas en train de péter un plomb. Deviens un team player. Respecte-toi. Permets-toi d’aller vite. Envoie de l’amour à ton futur toi. Écris ta putain de documentation technique.

Épilogue

Ça va mieux dis donc. J’ai bien aimé notre discussion. Je vais essayer de moins péter les plombs la prochaine fois. Fallait que j’en parle à quelqu’un. Bon voilà, c’est tombé sur toi. Tiens d’ailleurs si tu croises un autre dev essaye de lui en parler. Si tout le monde se met à documenter son code, on va vraiment se mettre bien.