Documentation technique interne : les quatre familles de contenu, où l'héberger, comment la tenir à jour et les symptômes qui trahissent un corpus mort.
La documentation technique interne rassemble ce qu’une équipe doit savoir pour faire tourner ses outils sans son auteur d’origine. Quatre formes la composent : le tutoriel, le guide pratique, la référence et l’explication. Les mélanger dans un même document produit un texte que personne ne lit, et que personne ne met à jour.
Ce que l’absence de documentation coûte réellement
La facture n’apparaît sur aucune ligne comptable. Elle se paie en interruptions, en décisions rejouées et en dépendance à une seule personne. Un développeur qui interrompt un collègue pour obtenir une information déjà connue quelque part consomme deux attentions au lieu d’une, et recommencera la semaine suivante.
Le programme de recherche DORA, qui publie l’état des lieux annuel des pratiques DevOps, a mesuré cet écart. Ses analyses associent une documentation interne de qualité à une performance d’équipe supérieure d’environ 25 %, et à une probabilité plus de deux fois supérieure d’atteindre les objectifs de fiabilité fixés. La documentation y apparaît comme un amplificateur : elle ne remplace aucune pratique technique, elle décuple l’effet de celles qui existent déjà.
Le second coût porte un nom dans les équipes techniques : le facteur d’autobus. Combien de personnes doivent disparaître pour que le projet devienne impossible à reprendre ? Quand la réponse est « une », chaque départ en congé devient un risque d’exploitation. Une procédure de reprise qui vit uniquement dans une mémoire n’est pas une procédure, c’est un pari. Le même raisonnement structure un plan de continuité d’activité : ce qui n’est pas écrit ne sera pas exécuté sous pression.
Quatre familles de contenu, quatre lecteurs distincts
Le cadre Diátaxis, formalisé en 2020 par Daniele Procida, développeur du projet Django et responsable ingénierie chez Canonical, part d’une seule question : que cherche à faire le lecteur au moment précis où il ouvre la page ? Quatre réponses possibles, donc quatre types de documents, jamais mélangés.
| Type | Ce que veut le lecteur | Forme attendue |
|---|---|---|
| Tutoriel | apprendre en faisant | parcours guidé, résultat garanti à la fin |
| Guide pratique | résoudre un problème précis | suite d’étapes, prérequis supposés acquis |
| Référence | vérifier un fait | fiche descriptive, exhaustive, sans narration |
| Explication | comprendre pourquoi | texte de fond, arbitrages et alternatives |
L’erreur la plus fréquente consiste à écrire un tutoriel qui digresse en explications. Le débutant décroche, l’expert s’agace, et la page finit par ne servir à personne. Sépare les deux : le tutoriel montre le chemin, l’explication justifie le tracé.
Cette séparation produit un effet secondaire utile sur la maintenance. Une référence se corrige ligne par ligne dès que le produit change. Une explication reste valable des années, parce qu’elle décrit un raisonnement, pas un état. En mélangeant les deux, tu condamnes la partie stable à être réécrite à chaque évolution technique.
Écrire pour quelqu’un qui n’a pas ton contexte
La norme IEC/IEEE 82079-1, publiée dans sa deuxième édition en 2019, s’applique à toutes les instructions d’usage, du pot de peinture à l’installation industrielle complète. Elle fixe des principes qui valent tels quels pour une procédure interne : exactitude, complétude, minimalisme. Ce dernier point compte autant que les deux autres. Une instruction noyée dans du contexte facultatif ne sera pas suivie.
Trois règles couvrent la quasi-totalité des cas rencontrés. Une action par étape, formulée à l’impératif. Le résultat observable écrit à la fin de l’étape, pour que le lecteur sache immédiatement s’il a réussi. Les prérequis en tête de page, avant la première commande, jamais découverts au milieu du parcours.
Écris la version courte d’abord, puis vérifie qu’elle tient debout sans ses phrases d’introduction. Si le premier paragraphe n’apporte rien d’actionnable, supprime-le. Une procédure interne n’a pas de lecteur à séduire : elle a un lecteur pressé, souvent en pleine gestion d’incident.
Les procédures métier gagnent à s’adosser à une cartographie des processus déjà établie. Sans cette vue d’ensemble, tu documentes des gestes isolés sans savoir lesquels comptent vraiment, ni qui les déclenche en amont.
Où ranger la documentation pour qu’elle survive
Le lieu de stockage détermine la fréquence de mise à jour bien plus sûrement que la bonne volonté des équipes. Une documentation éloignée du travail quotidien se périme dans le trimestre.
| Emplacement | Ce qu’il apporte | Sa limite |
|---|---|---|
| Dépôt de code, fichiers texte versionnés | correction dans la même relecture que le code | invisible pour les rôles non techniques |
| Espace wiki d’équipe | édition ouverte à tous, recherche correcte | pas d’historique de revue, pages orphelines |
| Suite bureautique partagée | aucun apprentissage requis | duplication, versions concurrentes, droits flous |
L’approche dite documentation comme code place les fichiers dans le dépôt, à côté des sources, en format texte simple. La modification passe par la même demande de fusion que le code, donc par la même relecture par un pair. Le contrôle qualité devient structurel au lieu de reposer sur la discipline individuelle.
Le compromis raisonnable dans une petite structure tient en trois lignes. La référence technique dans le dépôt. Les procédures transverses dans un espace unique accessible à tous. Rien d’important dans un fil de discussion. Ce principe rejoint celui de la gestion de parc informatique : la seule donnée qui vaut quelque chose est celle dont la date de dernière vérification est connue.
La mise à jour n’est pas une tâche annexe
Une documentation ne meurt pas d’un coup. Elle dérive. Chaque livraison non répercutée creuse l’écart entre le texte et le réel, jusqu’au jour où le lecteur cesse de faire confiance à la page et retourne interroger un collègue.
La norme ISO/IEC/IEEE 26515, dans sa version de 2018 intitulée « Developing information for users in an agile environment », traite exactement ce problème. Elle décrit comment l’information destinée aux utilisateurs se produit au rythme des itérations, et non dans une phase finale de projet. Transposé en interne, le principe tient en une phrase : une modification n’est terminée que lorsque la page correspondante est à jour.
Trois mécanismes rendent cette règle tenable :
- Inscrire la documentation dans la définition de terminé, au même titre que les tests
- Dater chaque page et afficher cette date en tête, pour rendre la péremption visible
- Nommer un responsable par page, plutôt qu’un responsable global du corpus
Le troisième point tranche un débat récurrent. Une responsabilité collective sur l’ensemble des pages produit une responsabilité nulle. Une responsabilité nominative page par page produit des relances possibles, donc des corrections réelles.
Une revue trimestrielle complète le dispositif : parcourir les pages dont la date dépasse six mois, valider ou archiver. L’archivage explicite vaut infiniment mieux qu’une page fausse laissée en ligne. Cette discipline ressemble à celle de la veille technologique, où l’élagage régulier des sources compte autant que la collecte.
Par où commencer quand tout est à écrire
Documenter l’intégralité d’un système n’arrive jamais. Le tri se fait sur trois critères, dans cet ordre précis.
Ce qui casse en production et réveille quelqu’un la nuit passe en premier. La procédure de redémarrage, la restauration d’une sauvegarde, la liste des accès d’urgence. Ces pages se lisent en situation dégradée, par une personne fatiguée et sous pression : elles doivent tenir sur un seul écran, sans défilement.
Vient ensuite ce qui se fait rarement. Une opération annuelle se réapprend entièrement à chaque exécution, alors qu’une tâche quotidienne s’exécute de mémoire. Le renouvellement d’un certificat, la clôture annuelle d’un outil comptable, la migration saisonnière d’un environnement appartiennent à cette catégorie.
Le troisième critère est le détenteur unique. Toute connaissance portée par une seule personne mérite une page, quelle que soit sa fréquence d’usage. La norme ISO 30401, publiée en 2018, pose ce cadre au niveau de l’organisation : elle fixe des exigences pour un système de management des connaissances et compte les informations documentées parmi ses conditions. La mobilité croissante des équipes et l’éclatement géographique des bureaux figurent parmi les motifs qui ont justifié sa rédaction.
L’ordre inverse, qui consisterait à documenter d’abord ce qui est simple et déjà maîtrisé, produit un corpus volumineux, rassurant et sans usage.
Six symptômes d’une documentation morte
- Aucune page n’affiche de date de dernière vérification
- Les nouveaux arrivants posent leurs questions en message privé plutôt que de chercher
- La même information existe à trois endroits, avec trois valeurs différentes
- Les captures montrent une interface qui n’existe plus depuis deux versions
- Personne n’a modifié une seule page depuis le trimestre précédent
- La recherche interne remonte les pages archivées avant les pages actives
Le premier symptôme reste le plus révélateur. Sans date visible, un lecteur ne peut pas évaluer le risque qu’il prend en suivant la procédure. Il choisit alors la solution la plus sûre à ses yeux : demander à un humain. La documentation existe, elle ne sert à rien.
Le quatrième mérite une nuance pratique. Les captures d’écran vieillissent bien plus vite que le texte et coûtent cher à refaire. Décris l’action par son intitulé plutôt que par sa position à l’écran, et réserve l’image aux rares cas où la disposition compte réellement pour comprendre.
La documentation comme premier support de formation
Une équipe qui documente correctement dispose du meilleur support d’intégration pour ses nouvelles recrues. Le parcours d’arrivée devient une suite de tutoriels réalisables en autonomie, et chaque question posée signale une page manquante ou fausse. Ce mécanisme fournit gratuitement le test de qualité le plus fiable : confie ta documentation à quelqu’un qui n’a jamais touché au système, observe où il bloque, corrige ce point précis dans la journée.
Le bénéfice dépasse l’intégration. Une connaissance écrite se discute, se conteste et se corrige, alors qu’une connaissance orale se transmet déformée et sans trace. Un désaccord technique qui se règle dans une demande de fusion sur un fichier de documentation laisse une décision datée, motivée, retrouvable dans trois ans.
Prochaine étape : liste les cinq procédures dont une seule personne connaît le déroulé, écris-les au format guide pratique cette semaine, puis fais-les exécuter par quelqu’un d’autre sans aucune assistance. Chaque blocage rencontré devient une correction à apporter le jour même, avant que le souvenir de l’essai ne s’efface.
