Rédiger une documentation claire : structure, style et captures d'écran

Rédiger une documentation technique, c'est transformer ce que tu sais en un texte qu'un lecteur précis peut suivre seul, sans hésiter et sans se tromper. Ce chapitre donne la méthode : analyser le lecteur, structurer le document, écrire des étapes vérifiables et des phrases simples, faire des captures d'écran utiles et les anonymiser, puis relire avec une liste de contrôle.

Avant d'écrire : qui lit, où, pour quoi faire ?

Cinq minutes de réflexion évitent des heures de réécriture. Note en tête de ton brouillon :

Le lieu et le moment de lecture changent tout. Une fiche réflexe lue à 3 h du matin par un technicien d'astreinte doit tenir sur un écran et commencer par l'action. Une procédure suivie en salle serveur sera peut-être imprimée : les liens cliquables n'y servent à rien, les noms exacts si.

Ce sont les questions qu'on se pose pour concevoir un écran d'application (IHM et ergonomie) : un guide utilisateur est lui aussi une interface, entre une personne et la tâche qu'elle veut accomplir.

Structurer : le plus important d'abord

Personne ne lit une documentation de la première à la dernière ligne. On la parcourt : le titre, les intertitres, le début des paragraphes, les tableaux. Ta structure doit donc répondre avant même qu'on lise vraiment.

• Un titre qui dit la tâche ou la question. Un verbe à l'infinitif pour un guide (« Restaurer un fichier supprimé »), une question pour une FAQ (« Que faire si l'imprimante n'imprime plus ? »), un nom précis pour une référence (« Plan d'adressage du siège »).
• Deux lignes de résumé juste sous le titre : à quoi sert le document, pour qui, combien de temps prend l'opération.
• Le plus important d'abord : la réponse, puis les détails (c'est la pyramide inversée des journalistes). Dans un compte rendu, le résultat vient avant l'historique.
• Des intertitres réguliers : un intertitre toutes les dix à vingt lignes permet de sauter directement à ce qu'on cherche.
• Une idée par paragraphe, et la première phrase du paragraphe dit laquelle.
• Le bon format pour chaque contenu : une liste numérotée pour des étapes dans l'ordre, une liste à puces pour des éléments sans ordre, un tableau pour comparer ou donner des valeurs, un bloc de code pour tout ce qui se tape.

Écrire des étapes qu'on peut suivre

Les étapes sont le cœur d'une procédure ou d'un guide. Une bonne étape se suit sans réfléchir et se vérifie : le lecteur sait s'il a réussi avant de passer à la suivante.

1. Une action par étape. « Ouvre GLPI, va dans le parc et ajoute le poste » fait trois étapes.
2. L'endroit avant l'action. « Dans GLPI, menu Parc > Ordinateurs, clique sur Ajouter. » Le lecteur sait où regarder avant de savoir quoi faire.
3. Le verbe d'action au début, toujours au même mode. Choisis l'impératif (« clique », « saisis ») ou l'infinitif (« cliquer », « saisir ») et garde-le dans tout le document. Dans ce cours, on tutoie ; dans un guide d'entreprise destiné aux salariés, on vouvoie le plus souvent.
4. Les valeurs exactes : le nom du champ, la valeur à saisir, la commande complète. « Mets le bon VLAN » n'est pas une étape ; « dans VLAN Tag, saisis 21 » en est une.
5. Le résultat attendu après l'action : « La fiche du poste s'affiche, avec le statut En stock. » C'est lui qui permet de détecter une erreur tout de suite, et pas trois étapes plus loin.
6. L'avertissement avant l'étape dangereuse, jamais après : « Attention, l'étape suivante redémarre le serveur et coupe les partages pendant deux minutes. »
7. Les conditions explicites : « Si le message Accès refusé apparaît, va à l'étape 9 ; sinon, continue. »

Voici la même consigne, mal puis bien écrite.

Avant. « Pour mettre en stock un poste, il faut aller dans GLPI et changer son statut, puis il faut penser à enlever l'utilisateur sinon ça pose problème pour l'inventaire et vérifier que c'est bon. »

Après.

1. Dans GLPI, menu Parc > Ordinateurs, recherche le numéro d'inventaire du poste (par exemple PC-0015) et ouvre sa fiche.
2. Dans le champ Statut, choisis En stock.
3. Vide le champ Utilisateur, puis clique sur Sauvegarder. Résultat attendu : la fiche se recharge, avec En stock dans le champ Statut et un champ Utilisateur vide.
4. Retourne à la liste des ordinateurs et filtre sur le statut En stock : le poste doit y apparaître.

La seconde version est plus longue, mais elle se suit en moitié moins de temps, et l'étape 4 prouve que le travail est fait.

Pour que le lecteur distingue d'un coup d'œil ce qu'il voit de ce qu'il tape, adopte des conventions et tiens-les dans tout le document :

Des phrases simples

La documentation n'est pas une dissertation : on ne cherche ni le style ni les synonymes, on cherche zéro ambiguïté.

• Des phrases courtes, une information par phrase. Au-delà de vingt-cinq mots, coupe.
• La voix active : « le script supprime les fichiers de plus de 30 jours », pas « les fichiers de plus de 30 jours sont supprimés ». La voix active dit qui agit.
• Un mot, une chose, partout. Si tu écris « serveur » dans le titre, n'écris pas « machine », « hôte » puis « VM » dans la suite : le lecteur croira qu'il y a quatre objets. Choisis aussi une seule façon de nommer chaque élément (srv-wiki, pas tantôt « le wiki », tantôt « la VM 190 »).
• Les sigles développés à leur première apparition : « le plan de reprise d'activité (PRA) ».
• Pas de mots qui jugent le lecteur : « simplement », « il suffit de », « évidemment ». Si c'était évident pour lui, il ne lirait pas.
• Le vocabulaire du lecteur : pour un salarié, « votre poste » et « l'imprimante du 2e étage » ; pour un technicien, PC-0008 et imp-etage2.

Les captures d'écran : quand et comment

Une capture d'écran montre où se trouve un élément et à quoi doit ressembler le résultat. Elle ne remplace jamais le texte : on ne peut ni la copier, ni la rechercher, ni la lire avec un lecteur d'écran, et elle vieillit à chaque mise à jour de l'interface.

Fais une capture quand l'élément est difficile à décrire (une petite icône sans libellé), pour montrer l'écran de résultat attendu, ou dans un guide destiné à des utilisateurs qui découvrent l'outil. N'en fais pas pour une commande ou un fichier de configuration : écris-les en texte dans un bloc de code, que le lecteur pourra copier. Une capture de terminal ne se copie pas, et une faute de frappe en recopiant suffit à tout faire échouer.

Pour qu'une capture soit utile :

1. Recadre sur la zone utile : la fenêtre concernée, pas tout l'écran avec la barre des tâches.
2. Annote : un rectangle autour de l'élément à cliquer, ou un numéro qui renvoie à l'étape. Une couleur unique et voyante pour toutes les annotations du document.
3. Garde une taille lisible : le texte de la capture doit pouvoir se lire sans zoomer. Plusieurs petites captures valent mieux qu'une grande illisible.
4. Ajoute une légende et un texte alternatif : la légende dit ce que montre la capture (« L'onglet Hardware de la VM 190 après l'étape 4 ») ; le texte alternatif décrit l'image pour ceux qui ne la voient pas.
5. Place-la juste après l'étape qu'elle illustre, jamais en annexe.
6. Note la version de l'outil capturé dans l'en-tête du document : quand l'interface change, tu sais quelles captures refaire.

Sous Windows, l'Outil Capture d'écran s'ouvre avec Windows + Maj + S ; sous macOS, Cmd + Maj + 4 capture une zone ; sous Linux, l'environnement de bureau fournit un outil équivalent (la touche Impr. écran sous GNOME).

Anonymiser une capture d'écran

Une capture montre souvent plus que ce que tu crois. Avant de la publier dans un wiki, un portfolio ou un dossier d'examen, passe-la en revue.

La meilleure anonymisation, c'est de ne rien avoir à cacher. Travaille avec un jeu d'essai fictif, des comptes de test (compta1, salarie1), des noms de domaine réservés aux exemples (sorbier.example, ad.sorbier.example) et les plages d'adresses réservées à la documentation (192.0.2.0/24, 198.51.100.0/24 et 203.0.113.0/24, que tu retrouves dans tout le fil rouge de Sorbier). Une capture faite sur de fausses données se publie sans retouche.

Quand il faut masquer quand même :

• Utilise un aplat opaque : un rectangle plein, d'une seule couleur, qui remplace les pixels. Le flou et la pixellisation sont à éviter pour du texte : un texte court légèrement flouté ou pixellisé peut parfois être reconstitué, surtout si l'on connaît la police et la longueur.
• Écrase l'image : exporte une nouvelle image (PNG) après le masquage. Un rectangle dessiné par-dessus un PDF ou un document de traitement de texte ne supprime rien : le texte reste sélectionnable et se copie-colle.
• Recadre plutôt que masquer quand c'est possible : ce qui est hors cadre n'existe plus.
• Vérifie le fichier final : zoome, essaie de sélectionner le texte masqué dans un PDF, relis les onglets et la barre de titre.

Accessibilité : une documentation que tout le monde peut lire

Une documentation accessible est plus facile à lire pour tout le monde, pas seulement pour les personnes en situation de handicap. Quelques règles, issues des mêmes principes que l'accessibilité web (RGAA et WCAG) :

• un texte alternatif sur chaque image qui porte une information ;
• des liens qui disent où ils mènent : « voir la [procédure de sauvegarde] », jamais « cliquez ici » ;
• des tableaux avec une ligne d'en-tête, et pas de tableau pour faire de la mise en page ;
• pas d'information portée par la couleur seule : « les lignes en rouge sont en erreur » ne sert à rien à qui ne distingue pas le rouge ; ajoute une colonne « Statut » ;
• une hiérarchie de titres sans saut (un titre de niveau 3 sous un titre de niveau 2), que les lecteurs d'écran utilisent pour naviguer.

Relire et tester son document

Le seul test qui compte : quelqu'un d'autre suit le document, et tu le regardes faire sans l'aider. Chaque fois qu'il hésite, revient en arrière ou te pose une question, il manque quelque chose dans le texte. Chez Sorbier, aucune procédure n'est marquée validée tant que l'autre technicien ne l'a pas suivie une fois.

Avant de faire tester, relis avec cette liste :

Exercices

Exercice 1 sur 4 Réécrire une consigne Réussi À revoir

Réécris cette consigne en étapes numérotées, avec le résultat attendu des étapes importantes.

« Pour donner accès au partage Comptabilité à un nouveau salarié, il faut le mettre dans le bon groupe dans l'AD, normalement c'est GG_Comptables, et ensuite il doit se déconnecter pour que ça marche, et on vérifie qu'il voit bien le lecteur. »

Voir la réponseMasquer la réponse de l'exercice 1

1. Sur le poste d'administration, ouvre Utilisateurs et ordinateurs Active Directory.
2. Recherche le compte du salarié (clic droit sur le domaine ad.sorbier.example, Rechercher), puis ouvre ses Propriétés.
3. Dans l'onglet Membre de, clique sur Ajouter, saisis GG_Comptables, puis Vérifier les noms et OK. Résultat attendu : GG_Comptables apparaît dans la liste des groupes du compte.
4. Demande au salarié de fermer sa session Windows, puis de la rouvrir : l'appartenance aux groupes n'est lue qu'à l'ouverture de session.
5. Sur son poste, dans l'Explorateur de fichiers, vérifie que le lecteur du partage Comptabilité apparaît et qu'il peut y ouvrir un fichier.

Ce qui a disparu : « normalement » (le document doit être sûr de lui ; si le nom du groupe peut varier, il faut dire où le vérifier), « pour que ça marche » (remplacé par la raison) et « on vérifie » (remplacé par un test précis).

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 2 sur 4 Des phrases simples Réussi À revoir

Réécris chaque phrase pour qu'elle soit claire et sans ambiguïté.

1. « Il est nécessaire que la vérification de l'espace disque soit effectuée préalablement à la mise à jour. »
2. « Il suffit simplement de relancer le service web. »
3. « Connectez-vous au serveur. Sur la machine, ouvrez un terminal. Sur l'hôte, tapez la commande. »
4. « En cas de souci, voir avec qui de droit. »

Voir la réponseMasquer la réponse de l'exercice 2

1. « Avant la mise à jour, vérifie qu'il reste au moins 2 Go libres : df -h /. » (La valeur de 2 Go est un exemple : la procédure doit donner le seuil réel.)
2. « Relance le service web : sudo systemctl restart nginx. »
3. « Connecte-toi à srv-wiki en SSH, puis tape la commande : … » Les trois mots « serveur », « machine » et « hôte » désignaient la même chose : on en garde un, et le nom exact.
4. « Si la vérification échoue, ouvre un ticket de priorité haute et préviens Antoine Mercier. » Le lecteur doit savoir qui, comment et quand.

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 3 sur 4 Que faut-il masquer ? Réussi À revoir

Tu veux mettre dans ton portfolio une capture de la fiche d'un ticket GLPI traité pendant ton stage. On y voit : le nom et l'adresse électronique de la salariée qui a ouvert le ticket ; le numéro d'inventaire du poste ; l'adresse IP privée du poste ; dans le suivi, un message du technicien qui contient le mot de passe temporaire donné à la salariée ; en haut de l'écran, un onglet du navigateur nommé « Messagerie : 3 non lus » ; le nom de l'entreprise dans le logo de GLPI.

Que fais-tu de chaque élément, et comment ?

Voir la réponseMasquer la réponse de l'exercice 3

• Nom et adresse de la salariée : données personnelles, à masquer par un aplat opaque (ou à remplacer par un nom fictif si tu refais la capture sur un environnement de test).
• Mot de passe temporaire : à masquer, et il ne doit plus être valable ; s'il l'était encore, il faudrait le faire changer. Remarque au passage qu'un mot de passe n'a rien à faire dans le suivi d'un ticket : c'est un point à signaler dans ton analyse.
• Onglet du navigateur : à recadrer, il n'apporte rien.
• Nom de l'entreprise : il faut l'accord de l'entreprise pour publier une capture de son outil interne ; sans accord, refais l'exemple dans ton environnement de test.
• Numéro d'inventaire et adresse IP privée : peu sensibles en soi, mais le plus sûr, dans un document public, reste de refaire la capture sur ton laboratoire avec des données fictives. C'est d'ailleurs ce qu'attend une commission : tes captures, sur ton environnement.

Méthode : recadrer, aplat opaque, export d'une nouvelle image PNG, vérification en zoomant. Pas de flou sur du texte.

Tu avais trouvé ?

Oui, j'avais bonPas encore

Exercice 4 sur 4 Capture ou texte ? Réussi À revoir

Pour chaque contenu, dis s'il faut une capture d'écran, du texte, ou les deux.

1. La commande qui crée le clone de la VM 190.
2. L'emplacement du petit bouton Regenerate Image dans l'onglet Cloud-Init de Proxmox.
3. Le contenu du fichier /etc/network/interfaces.
4. L'écran que voit un salarié quand son ticket a bien été envoyé.

Voir la réponseMasquer la réponse de l'exercice 4

1. Texte, dans un bloc de code : le lecteur doit pouvoir la copier.
2. Les deux : la phrase « onglet Cloud-Init, bouton Regenerate Image en haut de la liste » et une capture recadrée avec le bouton encadré.
3. Texte, dans un bloc de code : un fichier se copie, se compare avec diff et se recherche.
4. Capture (et une phrase qui dit ce qu'on doit y voir) : c'est le résultat attendu, qui rassure l'utilisateur et lui prouve que sa demande est partie.

Tu avais trouvé ?

Oui, j'avais bonPas encore