Une meilleure documentation

La documentation prouve son utilité lorsqu'elle élimine une question avant qu'elle ne soit posée. Lorsqu'elle échoue, le coût est silencieux et constant. Le travail se fait quand même, mais en interrompant la seule personne qui sait comment faire, en redécouvrant la même réponse toutes les quelques semaines, ou en devinant et en se trompant.

Les chiffres sont plus élevés que ce que la plupart des équipes supposent. Des enquêtes récentes estiment que le temps que les travailleurs du savoir passent à chercher de l'information représente environ un cinquième à un tiers de la semaine de travail, et les développeurs rapportent perdre huit heures ou plus par semaine à cause de documentation floue ou manquante. Une seule tâche non documentée détenue par une personne constitue un risque permanent. Le jour où cette personne est malade, la file d'attente derrière son étape s'arrête.

Il y a aussi un échec plus lent. Une page qui était correcte au lancement dérive à mesure que le processus change en dessous. Les gens la suivent, atteignent une étape qui ne correspond plus à la réalité, et apprennent à ignorer complètement la page. Une fois qu'une équipe cesse de faire confiance à sa documentation, elle cesse de la lire, et la documentation devient une pure surcharge : écrite, stockée, et jamais utilisée.

Bien faire les choses rapporte lors de l'intégration et dans le flux. Les équipes avec une documentation maintenue rapportent un temps d'adaptation nettement plus court pour les nouveaux arrivants et moins de transferts bloqués, car le récepteur peut agir sans réunion. Le rendement se mesure par les lecteurs atteignant le bon résultat du premier coup. Un document qui reste non lu ne livre aucune de ces valeurs. C'est pourquoi les mécanismes de la section suivante se concentrent sur le lecteur et la tâche, avec une couverture découlant de cet objectif.

Une meilleure documentation repose sur deux idées que vous pouvez appliquer à n'importe quelle page : écrire pour la personne qui effectue la tâche, et donner à chaque page un seul objectif.

Écrire pour l'exécutant, action en premier

La documentation minimaliste, l'approche étudiée par John Carroll chez IBM, part de la façon dont les gens se comportent réellement. Ils ne lisent pas un manuel de couverture à couverture. Ils veulent faire la chose, alors ils survolent pour trouver la prochaine action. Vous commencez donc par l'action et l'ordre, gardez chaque étape comme une véritable instruction, et placez l'historique et la justification sous les étapes où quelqu'un peut y accéder une fois qu'il est bloqué. Une erreur est traitée comme un moment normal dont la page aide le lecteur à se remettre, donc l'écriture consacre son espace aux étapes de récupération.

Une page, un objectif : les quatre de Diataxis

Le cadre Diataxis de Daniele Procida classe la documentation en quatre types selon deux axes, faire versus savoir, et apprendre versus travailler :

• Tutoriel : une leçon guidée qui renforce la confiance d'un débutant. Le lecteur apprend, donc vous choisissez le chemin et éliminez chaque décision.
• Guide pratique : des instructions orientées vers un objectif pour une personne compétente résolvant un problème réel au travail. Il suppose une connaissance de base et les amène à un résultat.
• Référence : des faits précis et complets à consulter, sans narration. Pensez à une table de paramètres ou une liste de champs d'API.
• Explication : le contexte et le pourquoi, lu en dehors de la tâche pour approfondir la compréhension.

La règle qui fait le travail est de garder ces éléments séparés. Un guide pratique qui s'arrête pour enseigner perd le lecteur expérimenté ; une référence alourdie par une histoire est lente à parcourir. La plupart des pages confuses sont deux ou trois types fusionnés en un seul.

Rendre les décisions et la récupération explicites

Une tâche réelle bifurque. Écrivez la bifurcation comme le lecteur la rencontre : approuvé ? oui -> envoyer au demandeur ; non -> retourner au propriétaire avec la raison. Ensuite, ajoutez la ligne de récupération : lorsqu'une étape échoue, nommez la première chose à vérifier. Indiquez les prérequis dès le départ, et indiquez à quoi ressemble le "terminé" pour que le lecteur sache quand s'arrêter.

Empêcher la dérive

Donnez à la page un seul propriétaire responsable, la personne responsable de sa justesse, et un déclencheur de révision lié au travail, de sorte que le changement de processus force le changement de la page. Là où les faits vivent dans un système, générez la page à partir de cette source unique de vérité afin que la ressaisie ne soit jamais nécessaire. Après cela, vous pouvez écrire une page que quelqu'un que vous n'avez jamais rencontré peut suivre à froid.

Prenons un flux de travail de support. Une demande arrive, est triée, attend dans une file d'attente, est assignée, traitée, révisée, et renvoyée. L'équipe a une page appelée "Traitement des demandes de remboursement" et les nouveaux agents continuent d'escalader des cas qu'ils pourraient clore eux-mêmes. Lire la page montre pourquoi. Elle commence par trois paragraphes sur l'historique de la politique de remboursement, puis liste chaque champ de l'outil de remboursement, puis enterre les étapes réelles près du bas, sans orientation sur le cas qui nécessite un gestionnaire.

Cette page est trois types Diataxis fusionnés en un : explication (l'historique de la politique), référence (la liste des champs), et un guide pratique (les étapes), tous en compétition pour la même ouverture. Voici comment vous la corrigez.

1. Nommer le lecteur et l'unique tâche. Lecteur : un agent de support. Tâche : décider et traiter une demande de remboursement unique. Cela en fait un guide pratique.
2. Commencer par l'action. Première ligne : "Pour traiter un remboursement, ouvrez la demande dans l'outil et vérifiez le montant par rapport au seuil." L'historique de la politique est déplacé vers une page d'explication distincte, liée en bas.
3. Écrire la décision. montant inférieur à 200 $ ? oui -> approuver et rembourser ; non -> acheminer vers un gestionnaire pour approbation. Cette seule bifurcation est celle autour de laquelle les agents escaladaient.
4. Ajouter la récupération et le terminé. "Si le bouton de remboursement est grisé, vérifiez que la commande est marquée comme livrée." Terminé lorsque : "le client reçoit un courriel de confirmation et le cas est clos."
5. Diviser la référence. La liste champ par champ devient sa propre page de référence que l'agent consulte uniquement lorsqu'un champ n'est pas clair.

Avant, un nouvel agent escaladait environ la moitié de ses cas de remboursement et un agent senior répondait aux questions. Après, le guide pratique tient sur un écran, la décision est explicite, et les escalades se réduisent aux cas réellement difficiles. L'historique n'a pas disparu ; il a été déplacé là où quelqu'un le lit une fois, pas chaque fois qu'il traite un remboursement.

Les pièges ici sont tentants parce que chacun donne l'impression d'être minutieux.

• Décrire le système au lieu de la prochaine action. Il est facile d'écrire ce qu'un écran contient, car c'est visible pendant que vous écrivez. Le lecteur a besoin de savoir quoi faire ensuite. Ouvrez chaque étape avec un verbe que le lecteur exécute.
• Documenter uniquement le chemin heureux. Le chemin heureux est rapide à écrire et semble complet. La réalité bifurque, donc un lecteur qui rencontre le cas malheureux est abandonné. Ajoutez la bifurcation commune et la première vérification de récupération, là où proviennent la plupart des questions réelles.
• Traiter les docs comme un écrit-une-fois. Une page écrite et abandonnée est pire qu'aucune page, car les gens lui font confiance puis se font avoir. Liez la page à un déclencheur de révision pour qu'un changement de processus force un changement de doc.
• Sur-documenter. Une page pour chaque micro-tâche crée un deuxième fardeau de maintenance et dilue les pages qui comptent. Documentez les tâches qui sont fréquentes, risquées ou détenues par une seule personne. Laissez les évidentes rester évidentes.

Deux véritables cas limites méritent un plan. D'abord, la page sans propriétaire clair, souvent un processus partagé qui traverse deux équipes. Sans propriétaire responsable, elle dérive plus rapidement, car tout le monde suppose que quelqu'un d'autre la mettra à jour. Nommez un propriétaire même lorsque le travail est partagé ; une responsabilité partagée n'est pas une responsabilité. Ensuite, les faits qui changent rapidement, comme une table de configuration qui change chaque semaine. Maintenue à la main, elle est obsolète en quelques jours. Générez cette page à partir du système d'enregistrement pour que la documentation ne puisse pas être en désaccord avec la réalité. Avec les pages individuelles gérées, la question devient comment garder de nombreuses pages vivantes au sein d'une équipe.

Une bonne page est une compétence artisanale. Un ensemble de documentation qui reste correct au sein d'une équipe est un système, et le système est ce qui maintient le travail en flux au lieu de stagner sur la connaissance tribale.

La version légère des docs-as-code fonctionne même pour les équipes non techniques : gardez la page près du travail qu'elle décrit, révisez un changement de la même manière que vous révisez le travail lui-même, et faites de la mise à jour du doc une partie de la définition de terminé pour changer le processus. Lorsqu'un développeur modifie le code et met à jour le commentaire dans le même commit, la doc ne peut pas dériver ; le même couplage fonctionne pour une procédure et sa page. Le principe est de mettre à jour le doc dans le même mouvement que le changement, pendant qu'il est frais et avant qu'une tâche distincte puisse glisser dans la file d'attente.

Soutenez-le avec deux habitudes. Assignez à chaque page un seul propriétaire responsable, en appliquant la règle du propriétaire unique responsable qui empêche la page orpheline. Et définissez des déclencheurs de révision liés à des événements réels, une sortie, un changement de politique, ou un audit trimestriel, afin que la page soit vérifiée selon un calendrier au lieu d'attendre que quelqu'un remarque qu'elle est incorrecte. Un passage trimestriel qui retire les pages mortes est aussi important que d'en écrire de nouvelles, car un ensemble plus petit et fiable vaut mieux qu'un grand ensemble obsolète.

Cette pratique se connecte au reste du flux. Un transfert n'est aussi bon que la documentation qui l'accompagne, et le récepteur qui fixe la barre là est le même exécutant pour lequel vous écrivez ici. Traitez l'ensemble de documentation comme faisant partie du flux de processus lui-même, possédé et maintenu en même temps que le travail qu'il décrit. Le principe durable à garder : une page existe pour amener un lecteur au bon résultat du premier coup, et elle est vivante tant que quelqu'un la possède et que quelque chose la force à rester vraie.