Rédiger une documentation technique compréhensible

Objectif

Le lectorat disposant du bagage présupposé comprend le texte dès la première lecture et sait ensuite quoi faire — sans question de clarification et sans avoir à joindre la personne qui a rédigé le texte.

Prérequis

Un lectorat nommé (personne nouvellement arrivée, exploitant, agent appelant) et un but nommé. Le modèle Diátaxis (cité) distingue quatre types de textes ayant des fonctions différentes : les tutoriels pour apprendre, les guides pratiques pour une tâche concrète, la référence pour la consultation, l'explication pour la compréhension. Un texte qui veut être plusieurs de ces types à la fois n'en remplit aucun.

Étapes

1. Choisir le type de texte et le rendre reconnaissable dès la première ligne : « Comment configurer X » est un guide pratique, « Comment fonctionne X » une explication. Le matériel de référence reste hors des guides pratiques et y est simplement lié.
2. Commencer par le résultat : ce que le lectorat saura faire après ce texte, quels prérequis s'appliquent, combien de temps cela prend approximativement.
3. Écrire à la voix active et au présent, et nommer l'agent de l'action : « Le serveur rejette la requête », « on envoie un token ». La ligne directrice citée justifie cela par le fait que la voix active indique clairement qui doit faire quoi ; le passif dissimule l'acteur.
4. Une idée par paragraphe, des phrases courtes, les séquences en liste numérotée, les choix en liste à puces. Chaque action numérotée commence par un verbe et possède un résultat vérifiable (« la sortie se termine par ok »).
5. Définir ou lier les termes lors de leur première occurrence et ne plus les faire varier ensuite : qui écrit « token », « clé » et « identifiant » (credential) pour désigner la même chose crée trois choses distinctes dans l'esprit du lectorat.
6. Remplacer les indications vagues : au lieu de « peut prendre un certain temps », donner un ordre de grandeur ou la fin observable ; au lieu de « le cas échéant », nommer la condition.
7. Vérifier par l'exécution : une personne du public visé ou un agent exécute le guide en s'appuyant uniquement sur le texte ; chaque endroit où une question se pose ou où l'on devine est une lacune du texte, pas du lectorat.
8. Placer la date, la version et le champ de validité au début ; supprimer les sections obsolètes plutôt que de les laisser marquées « obsolète ».

Résultat attendu

Moins de questions de clarification que le texte aurait dû anticiper ; des guides que les agents peuvent exécuter à partir du seul texte ; un wiki où référence et explication se trouvent séparément.

Limites et base de vérification

La clarté ne remplace pas l'exhaustivité ; en cas de conflit, la précision prime. Les règles d'écriture suivent la ligne directrice citée, la structuration suit le modèle Diátaxis ; un effet sur les agents n'est pas mesuré, mais proposé comme méthode de vérification.