Écris ta documentation technique bordel de merde

É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 ?



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é.



documentation technique


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.



documentation technique


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.



wtf


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.

Qui me parle ?

jesuisundev
Je suis un dev. En ce moment, je suis développeur backend senior / DevOps à Montréal pour un géant du jeux vidéo. Le dev est l'une de mes passions et j'écris comme je parle. Je continue à te parler quotidiennement sur mon Twitter. Tu peux m'insulter à cet e-mail ou le faire directement dans les commentaires juste en dessous. Y'a même une newsletter !

Pour me soutenir, la boutique officielle est disponible ! Sinon désactiver le bloqueur de pub et/ou utiliser les liens affiliés dans les articles, ça m'aide aussi.

17 commentaires sur “Écris ta documentation technique bordel de merde”

  1. Mais bordel de merde…. c’est tellement vrai !

    Et faut qu’elle soit KISS ! Tant pour l’enrichir que pour la lire !

    Quand j’ai commencé à m’amuser avec un raspberry pour apprendre les bases de l’IT, que j’ai dû recommencer mon installation parce que j’ai merdé et que…. je suis obligé de rechercher de nouveau TOUTES les infos pour que ça remarche comme je le souhaitai….
    Tu pleures de ne pas avoir documenter tes actions !

    Aujourd’hui j’ai toujours un traitement de texte ou un bloc note d’ouvert !

  2. Un GROS +1 sur tout ça. Comme disait je-sais-plus-qui : « Documentation is like sex : when it’s good, it is very good. And when it’s bad, it’s better than nothing. » 😉
    Blague à part, oui, c’est utile, et l’argument de « j’ai pas le temps » se résume TOUJOURS à faire perdre du temps aux suivants dans la chaîne. A l’échelle d’une équipe de dév ou d’une boîte, c’est tout simplement même pas rentable. (Bon, faut aussi le dire aux chefs de projets, paske sur l’autel des deadlines à la c*n, qu’est-ce qu’on sacrifie en premier, d’après vous ?)
    En pratique, j’ajouterai aussi que la doc doit être écrite ET maintenue : une doc obsolète, c’est presque pire que pas de doc du tout si ça t’envoie sur des fausses pistes où tu crois avoir tout bien fait correctement. Pour les stressés de la page blanche, outre le template de doc minimaliste, n’oublions pas qu’un schéma vaut 1000 mots et qu’un petit diagramme (détaillé et à jour) est aussi une excellente façon d’expliquer les choses.

  3. « 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. »
    J’aimerais bien avoir quelques arguments sur cette phrase. En quoi c’est l’enfer si ton IDE pousse tout seul et que ton vhost n’est pas mutualisé avec un autre développeur ?

    C’est une vraie question 😉

    1. Tout le monde poussait sur le même serveur dev.
      C’était impossible pour nous de séparer l’env dev.
      Donc on testait toutes nos affaires mergées en même temps au même endroit.

  4. Ha, ça fait plaisir de te lire quand t’es en colère.

    Encore une fois, je suis entièrement d’accord avec toi, surtout quand tu dis d’être honnête vis-à-vis de la dette technique. Reconnaître qu’on a fait un script en vitesse, et qu’il faut y repasser, ce n’est pas un indice de manque de compétence, mais une preuve de courage, et de lucidité.

    Bon, je vous laisse, j’ai de la doc technique à rédiger (je plaide coupable).

  5. Si effectivement certains usent du temps comme argument, d’autres quand tu leurs demande de documenter te répondent ‘Oui, mais on ne peut pas TOUT documenter.’
    Et c’est vrai, on ne peut pas tout documenter, on s’autorisera donc à ne rien documenter ou si peu.

T'en penses quoi ?

Your email address will not be published. Required fields are marked *