Écrire clair : réponse d'abord, phrases courtes, étapes vérifiables

30 min
Quiz · 6 questions

Par Stéphane Robert mis à jour le 13 octobre 2026

Améliorer cette page

Que voulez-vous signaler ?

L’issue s’ouvre déjà remplie avec le titre et l’adresse de cette page.

Une page technique est claire quand le lecteur trouve la réponse dans les premières lignes, la lit en phrases courtes, et peut vérifier après chaque étape qu'il est sur la bonne voie. Cette leçon donne les gestes pour y arriver : ouvrir par la réponse, écrire une idée par phrase, nommer chaque chose d'un seul mot, décrire des étapes dont le résultat s'observe, et tenir les règles d'accessibilité de base. Vous les appliquerez à un vrai paragraphe confus, puis à votre propre page avec une grille de relecture.

Ce que vous allez apprendre

Ouvrir une page et chaque section par la réponse, avec des titres qui disent ce que la section apporte
Réécrire un paragraphe confus en phrases courtes, à la voix active, avec des termes définis et constants
Écrire des étapes à une action, avec un résultat attendu observable et la conduite à tenir en cas d'écart
Appliquer les règles d'accessibilité de base : titres hiérarchisés, liens explicites, texte alternatif, information jamais portée par la seule couleur

Aucun prérequis au-delà de savoir éditer un fichier texte. Les exemples sont écrits en Markdown, un format de texte brut où un ## en début de ligne marque un titre et un 1. une étape numérotée. La syntaxe elle-même est enseignée dans la leçon Markdown, qui suit celle-ci.

Pour qui écrit-on ?

On écrit pour une personne précise, qui a une question ou une tâche, et qui n'a pas votre contexte. Le cours de Google Technical Writing One le dit ainsi : une bonne documentation donne à son public les connaissances et les compétences pour accomplir une tâche, en tenant compte de ce qu'il sait déjà. Avant d'écrire, demandez-vous qui lit, ce qu'il sait et ce qu'il veut faire.

Le piège a un nom, que le même cours reprend : la malédiction du savoir. Un expert oublie ce qu'il a appris un jour et saute les étapes qui lui semblent évidentes. Le lecteur novice bute sur un mot jamais expliqué et abandonne. La parade tient en une habitude : relire sa page en cherchant ce qu'une personne qui découvre le service ne peut pas deviner.

Le choix du type de document (tutoriel, guide pratique, référence, explication) est l'objet de la leçon Choisir le bon document. Ici, on suppose le type choisi et on travaille la qualité du texte.

Comment répondre d'abord ?

Placez la réponse dans la première phrase de la page, puis de chaque section, et développez ensuite. Les journalistes appellent cela la pyramide inversée : l'essentiel en haut, les détails en dessous. Le lecteur pressé qui s'arrête après deux lignes repart avec l'essentiel. Google le dit du paragraphe : la phrase d'ouverture est la plus importante, parce que les lecteurs occupés se concentrent sur elle et sautent parfois les suivantes.

Le schéma montre l'ordre à tenir : la réponse en haut, les détails ensuite, le contexte en dernier. Le lecteur pressé s'arrête après la première boîte et repart servi ; celui qui approfondit continue.

Source · SVG

Comparez deux ouvertures pour la même page. La première, « Dans ce document, nous allons revenir sur le contexte du service de facturation, puis nous verrons comment l'exploiter », annonce le contenu sans le donner. La seconde, « Pour redémarrer le service de facturation, exécutez sudo systemctl restart billing-api, puis vérifiez qu'il répond. Comptez 2 minutes », donne la commande, la vérification et la durée. Si le lecteur n'a besoin que de la commande, il l'a déjà.

Les titres suivent la même règle : ils disent ce que la section apporte, pas le sujet dont elle parle. « Redémarrer le service sans perdre de commandes » vaut mieux que « Redémarrage », et « Divers » ne dit rien. Formuler le titre comme la question du lecteur, « Comment redémarrer le service ? », le rend repérable en parcourant la page et dans un moteur de recherche.

Une section se lit parfois seule, après un lien direct ou une recherche. Ouvrez-la par une phrase qui la rend compréhensible sans le reste : elle nomme le sujet et donne la réponse, au lieu de dire « comme vu ci-dessus ».

Comment écrire des phrases courtes et sans ambiguïté ?

Une phrase porte une seule idée, et c'est l'acteur qui fait l'action. Le cours de Google compare le texte à du code : plus une instruction est courte, plus elle est facile à lire et à maintenir. Quatre gestes en découlent.

Couper : une phrase qui contient deux idées en devient deux.
Lister : une phrase qui énumère, ou qui contient un « ou » de choix, se transforme en liste à puces.
Élaguer : « procéder à la vérification de » devient « vérifier », « est en mesure de » devient « peut ».
Passer à l'actif : nommer qui fait l'action.

Le dernier geste mérite un exemple. Le cours définit la voix active comme la structure acteur, verbe, cible, et la voix passive comme l'inverse ou l'omission de l'acteur. En documentation, c'est cette omission qui coûte : « Le service doit être redémarré » ne dit pas qui doit agir, alors que « Redémarrez le service » le dit. Dans une description de comportement, on nomme l'acteur : « Le planificateur purge les journaux chaque nuit » vaut mieux que « Les journaux sont purgés chaque nuit ». La voix passive reste correcte quand l'acteur est inconnu ou sans importance, mais elle ne doit pas être le réflexe.

Les mots comptent autant que les phrases. Le cours donne trois règles : définir ou relier un terme nouveau, employer le même mot pour la même chose dans tout le document, et développer un sigle à sa première occurrence. Sur le deuxième point, il cite un ingénieur : devant deux mots qui semblent synonymes, le lecteur se demande si l'auteur veut signaler une différence subtile. Dans une doc, « service », « démon », « application » et « billing » pour une seule chose font croire à quatre objets.

Dernier réglage, les pronoms. Dans « Lancez la migration. Cela modifie le schéma », « cela » désigne-t-il la migration, le lancement, autre chose ? Le cours conseille de remplacer le pronom par le nom, ou de le faire suivre d'un nom : « Cette migration modifie le schéma. » Les pronoms « il », « ils », « ceci » et « cela » sont les plus risqués.

Comment structurer paragraphes, listes et tableaux ?

Un paragraphe traite un sujet, s'ouvre par sa phrase la plus importante et reste court. Le cours situe le bon équilibre autour de trois à cinq phrases : au-delà d'environ sept, les lecteurs évitent le « mur de texte ». Une phrase qui s'écarte du sujet se supprime ou se déplace.

Choisissez ensuite la forme selon le contenu : une liste numérotée pour des actions dans un ordre précis, une liste à puces pour des éléments sans ordre et construits pareil (tous par un verbe, ou tous par un nom), un tableau pour comparer des éléments selon les mêmes critères. Chaque liste ou tableau est présenté par une phrase d'introduction, comme dans cette leçon : sans elle, le lecteur ne sait ni pourquoi il le lit ni comment le parcourir.

Comment écrire une procédure dont chaque étape se vérifie ?

Une étape vérifiable contient une action, le résultat attendu qui prouve qu'elle a réussi, et la conduite à tenir si le résultat est autre. Sans résultat attendu, le lecteur devine s'il a réussi, continue, et découvre l'erreur trois étapes plus loin, quand elle coûte plus cher à réparer. Quatre règles font une bonne procédure.

Un impératif, une action par étape. « Connectez-vous au serveur » est une étape ; « Connectez-vous, redémarrez le service et lisez les journaux » en est trois. Le cours note que les listes numérotées commencent souvent par un verbe à l'impératif.
Les prérequis avant les étapes. Accès, droits, outils, état de départ : découvrir à l'étape 5 qu'il manque un accès est la pire expérience de lecture.
Un résultat observable après l'étape. Une sortie de commande, un code retour, un état affiché, un fichier présent : quelque chose que le lecteur voit. « Le service est redémarré » n'est pas observable ; active affiché par une commande l'est.
Une branche d'échec. Dire quoi faire quand le résultat diffère : une correction, ou l'ordre de s'arrêter et d'appeler quelqu'un.

Le schéma montre cette boucle. Suivez le chemin épais : l'action mène au contrôle du résultat, et seule la réponse « oui » ouvre l'étape suivante. La branche « non » renvoie vers ce qu'il faut faire en cas d'écart.

Structure d'une étape vérifiable : action, résultat attendu, conduite si l'écart. Source · SVG

Voici une étape réelle. L'action est la commande ci-dessous, le résultat attendu est le mot qu'elle affiche, et la branche d'échec dit quoi faire sinon.

systemctl is-active billing-api

Le résultat attendu est active. Si la commande affiche failed ou inactive, le service n'a pas démarré : n'enchaînez pas, lisez les journaux (le fichier où le service note ce qu'il fait). La sortie de cette commande tient en un mot : préférez toujours une vérification qui répond par oui ou non à une sortie qu'il faut interpréter.

Comment rendre le texte accessible dès l'écriture ?

L'accessibilité se joue à la rédaction : un texte bien structuré se lit à l'écran, au lecteur d'écran et sur un petit appareil, sans travail supplémentaire. Google propose un cours dédié, Tech Writing for Accessibility, qui vise des documents utilisables par tous, y compris les personnes handicapées, par exemple celles qui utilisent un lecteur d'écran, un logiciel qui lit la page à voix haute.

Les règles ci-dessous se rattachent à des critères de succès des WCAG 2.2, les règles d'accessibilité du contenu web publiées par le W3C. Le tableau reprend les intitulés et les niveaux (A ou AA) de la spécification : un titre doit décrire son sujet ou son but (2.4.6), et le but d'un lien doit se déterminer par son texte, seul ou avec son contexte (2.4.4).

Règle de rédaction	Critère WCAG 2.2
Faire de vrais titres, qui décrivent la section	1.3.1 Info and Relationships (A) et 2.4.6 Headings and Labels (AA)
Écrire des liens qui disent où ils mènent	2.4.4 Link Purpose (In Context) (A)
Décrire les images utiles	1.1.1 Non-text Content (A)
Ne pas coder l'information par la couleur seule	1.4.1 Use of Color (A)

Chaque règle a son geste. Pour les titres, utilisez la syntaxe de titre du format (##), jamais un paragraphe en gras qui y ressemble : seul un vrai titre est reconnu comme tel par un lecteur d'écran, qui permet de naviguer de titre en titre. Descendez d'un niveau à la fois, sans passer d'un ## à un ####. Les WCAG n'interdisent pas explicitement le saut de niveau, mais la technique G141 (« Organizing a page using headings ») recommande des titres correctement imbriqués : une hiérarchie régulière garde le plan navigable.

Pour les liens, le texte doit faire sens hors contexte, car un lecteur d'écran peut énumérer les liens d'une page : une liste de « cliquez ici » n'apprend rien. Écrivez « le guide de restauration des sauvegardes », jamais « cliquez ici » ni l'URL brute.

Pour les images, rédigez un texte alternatif qui dit ce que l'image apprend au lecteur, pas ce qu'elle est : « Courbe de latence : 200 ms jusqu'à 14 h, puis 2 s après le déploiement » plutôt que « graphique ». Si l'image est purement décorative, l'alternative reste vide. Ici, la règle de base suffit : elle sert aussi pour les schémas et les captures.

Pour la couleur, ne dites jamais « les lignes en rouge » : un lecteur daltonien ou un lecteur d'écran ne les distingue pas. Ajoutez un mot, un symbole ou une étiquette, comme « Erreur : » devant la ligne.

Comment réécrire un paragraphe confus, pas à pas ?

On réécrit en appliquant les règles dans l'ordre : réponse d'abord, puis prérequis, une action par étape, un résultat observable, une branche d'échec. Voici un paragraphe réaliste, tel qu'on en trouve dans une doc interne.

Pour redémarrer le service (aussi appelé le démon, ou billing), il suffit
simplement de se connecter au serveur et de le relancer, ce qui est
normalement assez rapide, mais il faut faire attention à ce que la file
d'envoi soit vide avant, sinon des commandes risquent d'être perdues, et une
fois que c'est fait, on regarde si ça tourne bien et si l'API répond, sinon
on appelle l'astreinte. Cela peut prendre un peu de temps.

Un lecteur en situation n'y trouve ni commande ni condition claire. Voici les défauts, dans l'ordre où on les corrige.

La réponse est enfouie. La commande n'apparaît nulle part. On ouvre par elle, avec la durée.
Le service a trois noms : « service », « démon », « billing ». On choisit billing-api, le nom que systemd (le gestionnaire de services de Linux) donne à ce service, et on s'y tient.
Une phrase de 70 mots mêle cinq idées. On coupe en étapes courtes.
« Il suffit simplement » et « normalement assez rapide » minimisent sans rien dire, et le lecteur qui échoue se croit en faute : ce qui est simple pour vous ne l'est pas pour qui découvre l'outil. On supprime, on chiffre : 2 minutes.
Le prérequis est noyé au milieu (« attention à ce que la file soit vide »). On le sort avant les étapes.
Aucun résultat attendu. « Voir si ça tourne bien » n'est pas observable. On le remplace par active et un code HTTP.
La conduite en cas d'échec est une demi-phrase. On en fait une branche explicite pour chaque contrôle.

Voici le résultat, en Markdown. Les lignes de commande y sont indentées sous l'étape pour rester dans la liste.

## Comment redémarrer le service de facturation ?

Pour redémarrer le service `billing-api`, exécutez
`sudo systemctl restart billing-api`, puis vérifiez qu'il répond. Comptez
2 minutes.

Avant de commencer, vérifiez deux points :

* Vous avez un accès SSH sudo au serveur `billing-01`.
* La file d'envoi du tableau de bord Facturation affiche 0. Sinon, attendez :
  un redémarrage perdrait les commandes en cours d'envoi.

1. Connectez-vous au serveur :

       ssh billing-01

   Résultat attendu : l'invite de commande affiche `billing-01`.

2. Redémarrez le service :

       sudo systemctl restart billing-api

   Résultat attendu : la commande rend la main sans message d'erreur.

3. Vérifiez que le service est actif :

       systemctl is-active billing-api

   Résultat attendu : `active`. Si vous lisez `failed` ou `inactive`, ne
   continuez pas : lisez `journalctl -u billing-api -n 50`, puis appelez
   l'astreinte.

4. Vérifiez que l'API répond :

       curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/health

   Résultat attendu : `200`. Si vous lisez `000`, le service n'écoute pas
   encore : attendez 10 secondes et relancez la commande. Si le code
   commence par `5`, appelez l'astreinte.

Dans cet exemple, billing-api, billing-01 et le port 8080 sont des noms d'illustration, à remplacer par ceux de votre service. ssh ouvre une session sur le serveur distant. Les deux commandes de vérification fonctionnent ainsi : systemctl is-active affiche l'état du service, et curl -w '%{http_code}' affiche le code de réponse HTTP de l'API, ou 000 quand la connexion échoue.

Relisez le résultat avec les règles en tête : la réponse est en haut, le service porte un seul nom, le prérequis précède les étapes, et chaque étape a une action, un résultat observable et, quand il le faut, une branche d'échec. C'est plus long que le paragraphe d'origine, mais chaque ligne sert, alors que l'original obligeait à deviner.

Comment relire sa propre page ?

Relisez votre page avec une grille de neuf questions, en une passe par thème. Un terme jamais défini, un « simplement », un lien « cliquez ici » ou une étape sans résultat attendu s'y repèrent vite. Tout vérifier à la fois fait manquer la moitié des défauts. Appliquez cette grille à une page que vous avez écrite, et réécrivez les passages où la réponse à une question est non.

Thème	Question
Lecteur	Qui lit cette page, et que sait-il déjà ?
Réponse	La première phrase de la page et de chaque section donne-t-elle la réponse ?
Titres	Chaque titre dit-il ce que la section apporte, sans saut de niveau ?
Phrases	Chaque phrase porte-t-elle une seule idée, avec un acteur identifiable ?
Mots	Chaque chose a-t-elle un seul nom, et les sigles sont-ils développés ?
Étapes	Chaque étape a-t-elle une action, un résultat observable et une branche d'échec ?
Prérequis	Sont-ils tous listés avant la première étape ?
Liens	Le texte de chaque lien nomme-t-il sa destination ?
Images et couleurs	Chaque image utile a-t-elle un texte alternatif, et aucune information ne repose-t-elle sur la couleur seule ?

Le meilleur test reste un lecteur réel. Demandez à une personne qui ne connaît pas le service de suivre votre procédure sans rien vous demander : chaque fois qu'elle hésite, il manque une information dans la page. Pour écrire ce type de procédure en situation d'urgence, le guide Runbooks applique les mêmes règles.

À retenir

La réponse d'abord : première phrase de la page, puis de chaque section ; des titres qui disent ce que la section apporte.
Une idée par phrase, à la voix active, avec un acteur identifiable ; des paragraphes courts qui s'ouvrent sur leur phrase la plus importante.
Un mot par chose, défini à sa première occurrence ; les sigles sont développés une fois.
Une étape vérifiable : une action à l'impératif, un résultat observable, une branche d'échec ; les prérequis viennent avant.
Accessibilité de base : de vrais titres sans saut de niveau, des liens qui nomment leur destination, un texte alternatif pour les images utiles, pas d'information portée par la seule couleur.
Relecture : une passe par thème avec la grille, puis un lecteur réel qui suit la procédure sans rien demander.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin