Avec les années j'ai vu beaucoup de chose en termes de documentations techniques dans les différents projets où je suis passé. J'ai aussi été amené à rédiger pas mal de documentation moi-même. Je ne prétends pas avoir la recette ultime et magique pour une bonne documentation technique, mais j'ai adopté quelques réflexes au fil des années, en particulier quand il s'agit de rédiger une page de documentation technique dans le cadre de périmètre d'une équipe, et je me suis dit que partager ça pouvait donner des idées à d'autres !
De quelle doc on parle ?
Il y a beaucoup de documentation technique : le README du projet, le Confluence/Wiki de l'équipe, la documentation utilisateur, les tests, les tickets dans Jira, etc.
Même si toutes ces ressources sont importantes à leurs façons, je vais me concentrer sur la doc qu'on fait pour notre équipe, le genre de doc qu'on fait pour ne pas perdre de temps quand on devra refaire une tâche, ou qui va nous servir quand on devra toucher un aspect de l'application un peu complexe voir partager le fonctionnement avec un nouvel arrivant.
Toute la doc qui pour moi s'adresse à l'équipe, qui n'a pas destination à être diffusée loin, mais à garder de la connaissance par écrit dans l'équipe.
Pourquoi faire de la doc ?
Pour commencer : je suis partisan de dire que si on fait un code de qualité, on a peu besoin de documentation. Je sais que tout le monde n'est pas d'accord, mais pour moi c'est une évidence : si le code est bien fait, il peut se lire très facilement, et c'est forcément la vérité sur ce qui se passe en production car c'est directement ce qui se passe en production.
Après évidemment si vous écrivez des choses du genre, ça ne fonctionne pas :
function checkValueIsYes(value: string): boolean {
return value === 'blue';
}
Mais on peut espérer que ça n'arrive pas trop souvent...
Dans tous les cas, comme je disais avec ce genre de pratique "on a peu besoin de documentation", j'ai bien dit peu et pas pas. On a toujours des éléments qui ont besoins de plus de contextes, des liens, des contacts, des infos complémentaires, etc. Et parfois c'est compliqué de les mettre dans le code.
C'est là qu'arrive la documentation d'équipe, contenant des pages qui doivent aborder un point précis chacune pour être lue rapidement, donner le minimum d'info qui permet de faire gagner du temps. Souvent la question que je me pose c'est "qu'est-ce que j'aurais aimé avoir comme informations avant de commencer à travailler sur X ?" et ça me donne généralement une bonne trajectoire !
Le minimum vital !
Il y a quelques points qui pour moi doivent être systématiquement présents dans une bonne page de documentation : la date de mise à jour (si pas calculée automatiquement), les auteurs de la doc (si pas calculé automatiquement), un contexte, les liens utiles, les contacts, les applications concernées (si on a plusieurs applications / briques en charge).
La date de mise à jour est sans doute l'élément LE plus important parmi les éléments les plus importants ! Elle va permettre au lecteur de se faire un avis sur la fraîcheur de la doc, et donc se faire un avis sur le niveau de confiance qu'il peut lui apporter : plus elle est récente plus il y a une bonne chance qu'elle soit à jour, plus elle est ancienne plus il y a de chance qu'elle soit obsolète… Si c'est calculé automatiquement par votre outil : laissez-le faire ! Gérer la date de mise à jour à la main implique que la mise à jour de cette info sera aléatoire et demandera la rigueur des personnes qui mettront à jour et je ne fais pas confiance en ces personnes, quand bien même je ferai surement partie de ces personnes moi-même ! Avoir la date permet aussi parfois de trier des documentations qui datent de différentes époques !
Les auteurs c'est un peu pareil côté mise à jour que la date : laissez l'outil le gérer autant que possible ! Pour ce qui est de l'usage c'est parfois pratique de pouvoir aller voir la personne qui a écrit la documentation pour avoir un complément d'information qui ne serait pas écrit (par oubli, on est humain, ça arrive !). Parfois la personne est partie mais tant pis on aura tenté de laisser un contact au sein de l'équipe ce qui évite parfois un syndrome courant de gens qui n'osent pas aller voir des personnes hors de l'équipe (je vous jure, dans la très grande majorité des cas, vous pouvez aller contacter quelqu'un d'une autre équipe, vous aurez une réponse, et parfois un coup de main directement en pair avec la personne ce qui vous fera gagner un temps fou !). À noter que j'ai bien indiqué "auteurs" au pluriel car on est parfois plusieurs à rédiger la version initiale mais il y a aussi souvent des mises à jour à faire donc n'hésitez pas à vous ajouter à la liste !
Le contexte c'est toujours pratique : ça peut être juste une phrase, parfois plusieurs paragraphes mais c'est histoire de donner un peu de cadre à ce pourquoi la documentation existe, donner quelques informations très larges sur le contexte. C'est peu utile quand on maîtrise un peu le contexte de travail de l'équipe mais quand on commence dans une équipe ça peut vous aider très très fortement !
Les liens utiles c'est une section que je vois vraiment trop peu : l'idée c'est de très simple donner des pointeurs vers tous les éléments qui pourraient être utiles à la personne qui lira la documentation : la documentation officielle de l'outil, le dépôt git avec les sources, un projet exemple, la documentation d'une autre équipe sur le sujet ou un sujet connexe, le swagger d'une api utile, un outil qui aide à tester une partie, etc. C'est sans limite, mais c'est tellement pratique de pouvoir retrouver tous les liens comme ça quand on débarque sur un sujet ! Parfois certains finiront par mourir (tant pis : remplacez-les si c'est possible en le découvrant ou supprimez-les simplement), mais tant que le lien est disponible on peut aller chercher une information qui se mettra à jour sans votre intervention. Si c'est un lien Internet, il est généralement possible de retrouver la page via Internet Archive, donc n'ayez pas trop peur des liens morts !
Autre information qui n'est pas assez répandue : les contacts ! Si vous savez qui gère l'outil clé indiquez son nom et son équipe, si vous avez une équipe qu'on peut contacter pour avoir des informations ou de l'aide dites-le, si même il existe un canal pour avoir du support, ne vous privez pas de donner l'information ! Dites-vous que chaque point de contact pourra permettre à quelqu'un dans le futur de travailler et que cette future personne sera peut-être vous !
La section "applications concernées" est utile seulement si notre équipe est en charge de plusieurs briques techniques / applications. Je sais que c'est typiquement le genre de section qui est mal (jamais ?) mis à jour, mais ça donne une idée quand même !
Et le reste ?
C'est difficile de vous dire exactement quoi écrire dans tous les cas, car c'est trop dépendant de chaque documentation.
Pour la suite de la documentation, j'essaie en général de faire une section pour chaque aspect important ou chaque question que je me suis posé en traitant le sujet. Est-ce que c'est une méthode permettant de garantir que la documentation est complète ? Non. Mais ça donne un point de départ qui peut toujours être complété plus tard, qui peut être partagé à l'équipe, qui peut être relu.
Si on est deux à avoir travaillé sur un sujet, je trouve que le plus efficace étant toujours qu'une des deux personnes rédige la première version de la documentation. Puis, à la manière des revues de codes, l'autre relit et complète/pointe ce qui manquerait.
Pensez aussi que certaines personnes sont plutôt visuelles et ont besoin d'un schéma pour comprendre : faire un schéma simple avec des outils comme Draw.io c'est rapide à faire, et les images issues de drawio sont éditables directement, donc c'est parfait ! Insérer une image c'est parfois un piège sinon : c'est compliqué à mettre à jour, donc ce n'est jamais mis à jour ! À défaut d'un format à la fois affichable et éditable, vous pouvez mettre un fichier "projet" en lien à côté de l'image pour facilité la mise à jour futur !
Dans le même temps : si vous mettez une image, pensez à toujours mettre une description aussi, déjà certaines personnes ne seront pas en mesure de voir l'image (entre les personnes aveugles et tous les handicaps qu'on peut croiser, autant faciliter la vie de tout le monde) ensuite un texte sera toujours plus facile à retrouver via une recherche !
Petit point aussi sur les morceaux de code. Éviter à la fois de mettre des morceaux de code trop long ou trop court. Je m'explique. Avoir un morceau de code trop court peut parfois louper des informations importantes qui vont le rendre inutilisable, dites-vous que quand vous lisez la doc, vous avez envie de pouvoir copier-coller et avoir quelque chose qui fonctionne directement (ou presque). Mais trop long va rendre la doc indigeste, car la personne va sauter les blocs de code et louper les informations que vous vouliez transmettre. Une option qui peut fonctionner c'est de créer un dépôt de code (ou un gist/snippet en fonction des cas) qui contient une version directement exécutable du code, mettre un lien vers ce dépôt tout en donnant dans la doc uniquement les extraits importants pour les expliquer. J'ai déjà fait ça et certes ça prend plus de temps mais c'est beaucoup plus exploitable ensuite !
Template de documentation
Ne prenez pas ce template comme une bible absolue, mais ça vous donne une idée de ce que j'ai en tête !
# [Contexte] Titre court mais direct
Auteurs : Anthony PENA
Mises à jour : 2025-04-22
## Sommaire (si généré sinon skip)
## Contexte
Donner un peu d'élément de contexte en quelques phrases.
## Liens
- quelque chose : http://example.com/quelque-chose
## Contacts
- John DOE (dev) : john.doe@super-boite.com
- Jane DOE (lead) : jane.doe@super-boite.com
## Applications concernées
## Archi globale
## Point important 1
## Point important 2
...
C'est assez simple non ?
Exemple
Comme une démonstration vaut mille mots, je vous fais un exemple de documentation que j'aurais pu faire sur un script que j'ai écrit pour le boulot.
# [NPM] Mise à jour des dépendances
Auteurs : Anthony PENA
Mises à jour : 2025-04-22
## Sommaire
- [Contexte](#contexte)
- [Liens](#liens)
- [Contacts](#contacts)
- [Applications concernées](#applications-concernées)
- [Applications concernées](#applications-concernées)
## Contexte
Pour mettre à jour les dépendances d'un projet NPM, il y a globalement deux options : soit éditer manuellement le package.json, soit utiliser la commande `npm install package@version`.
La première méthode demande d'ouvrir un éditeur de code / texte ce qui fait perdre un peu de temps quand on doit mettre à jour une dizaine de projets.
La commande npm fonctionne bien et est pratique pour mettre à jour en série des projets, mais va systématiquement ajouter un `^` devant de numéro de version, ce qui ne correspond pas à ce qu'on veut (décision tracé par cette [ADR](/lien/vers/l-adr-sur-les-versions-npm)).
Seule la première option était donc disponible, ce qui n'était pas très pratique.
Ici une présentation du script `npm-bump` qui vise à apporter le confort de `npm install` sans l'inconvénient mentionné.
> Note : il existe aussi la commande `npm update` mais elle suit les préfixes de dépendance qu'on n'utilise pas donc ça ne fonctionne pas dans notre cas non plus.
## Liens
- Doc officielle de `npm install` : https://docs.npmjs.com/cli/v11/commands/npm-install
- Doc officielle de `npm update` : https://docs.npmjs.com/cli/v11/commands/npm-update
- Dépôt de npm-bump : https://git.super-boite.com/anthony.pena/npm-bump
- guide d'installation de npm-bump : https://git.super-boite.com/anthony.pena/npm-bump/README.md#Installation
## Contacts
- Anthony PENA (lead dev) : anthony.pena@super-boite.com
## Applications concernées
Tous les projets NPM sans setup préalable.
## Installer le script
> Note : En priorité se référer à la documentation officielle : https://git.super-boite.com/anthony.pena/npm-bump/README.md#Installation !
- cloner le dépôt
- lancer `npm ci`
- installer le script en global : `npm run install-script`
Normalement vous devez pouvoir exécuter `npm-bump --version` et avoir une version qui s'affiche. Si oui l'installation en global est fonctionnelle.
## Lancer le script sur un dépôt
- Aller dans un projet NPM (dans le dossier qui contient un `package.json`).
- Lancer la commande `npm-bump package1@version package2@version ...`
- Attendre que l'exécution se termine (le script va à la fois mettre à jour le `package.json` et lancer l'installation des packages via `npm install` donc ça peut prendre un peu de temps)
- Commiter les changements après validation
## Utiliser le script pour un projet qui dépend de `--legacy-peer-deps`
Pour certains projets, on a encore des blocages à utiliser les nouvelles résolutions de packages, donc doit passer par `npm install --legacy-peer-deps` (qui utilise l'ancien mode) ou `npm install --force` (qui ne valide plus les peer dependancies, ce qui est une très mauvaise pratique). Le script `npm-bump` accepte le flag `--legacy-peer-deps` à place n'importe où dans la liste des packages à mettre à jour pour que ça fonctionne sur ces projets.
Exemple :
```Bash
npm-bump vite@x.y.z --legacy-peer-deps
```
## Conseils d'usage
`npm-bump` est pensé pour s'utiliser dans un enchaînement de commande permettant de gagner du temps pour mettre à jour les projets. Exemple d'enchaînement de commande qu'on peut utiliser (sous Linux ou dans un WSL) :
```Bash
git pull && cd ./front && npm-bump vite@x.y.z vitest@x.y.z && npm run lint:fix -- package.json && npm run test && cd ../e2e && npm-bump @playwright/test@1.51.1 && npm run lint:fix -- package.json && npm run test && git add -u && git commit -m "chore(front+e2e): update deps" && git pull -r && git push
```
Conclusion
Comme je disais au début, ce n'est pas une recette magique parfaite, mais plutôt une sorte de récapitulatif de ce que j'ai en tête quand je commence la rédaction d'une page de documentation pour mon équipe. Est-ce que c'est parfait ? Non. Est-ce que ça marche au moins pas trop mal ? Je trouve que oui.
Comme d'habitude : si vous avez des idées, des pistes, vous voyez des choses qui pour vous manquent, n'hésitez pas à me contacter pour échanger sur le sujet, je serais très content d'échanger sur le sujet pour améliorer ma propre pratique ! 🤓
Crédit photo : Générée via Mistral AI avec le prompt suivant
Créez une illustration représentant une équipe de développeurs travaillant ensemble dans un espace de bureau moderne. L'image doit inclure :
Une équipe de développeurs assis autour d'une table, chacun avec un ordinateur portable ouvert, affichant des fichiers de documentation et des extraits de code.
Un tableau blanc en arrière-plan avec des schémas et des diagrammes dessinés à la main, symbolisant la planification et la collaboration.
Des icônes ou des logos d'outils de documentation comme Confluence, GitHub, et Draw.io, intégrés dans l'environnement de travail.
Des fichiers de documentation visibles sur les écrans, tels que des PDF et des fichiers Markdown, avec des sections bien structurées.
Des éléments de communication comme des messages ou des notifications sur les écrans, montrant l'interaction entre les membres de l'équipe.
Une horloge ou un calendrier sur le mur pour symboliser l'importance des mises à jour régulières.
Des descriptions textuelles à côté des images ou des schémas pour souligner l'accessibilité.Utilisez des couleurs vives et un design moderne pour rendre l'image attrayante et professionnelle.