Rédiger une documentation technique
Écrire un mode opératoire qu'on peut suivre sans deviner : le lecteur, les prérequis avant les étapes, une action par étape, le résultat attendu, l'avertissement avant l'action et un seul mot par chose.
- 26 cartes
- 5 thèmes
- Gratuit
Le programme, thème par thème
Le poids de chaque thème suit celui que lui donne l'examen.
- Notions
- Questions
- Ranger et relier
- Mises en situation
- Comprendre
Quelques cartes du deck
Mode opératoire : de quoi s'agit-il ?
Voir la réponse
Texte qui décrit, étape par étape, comment réaliser une tâche précise.
Il doit pouvoir être suivi par quelqu'un qui n'a jamais fait la tâche, sans rien deviner : ce qui paraît évident à l'auteur ne l'est pas pour le lecteur.
Laquelle de ces étapes est bien écrite pour un administrateur ?
- Relancez le service avec la commande
sudo systemctl restart nginx. - Il faudra ensuite penser à éventuellement relancer le service si besoin.
- Le service est relancé, puis la configuration est vérifiée.
- Relancer le service et vérifier qu'il tourne bien.
Voir la réponse
Relancez le service avec la commande
sudo systemctl restart nginx.La bonne étape a un verbe d'ordre, une seule action et la commande exacte. La première est vague (« éventuellement », « si besoin »), la deuxième est passive et sans acteur, la troisième réunit deux actions.
- Relancez le service avec la commande
Une étape contient … action, avec un verbe à l'… ou à l'infinitif : « Ouvrez le fichier ».
Voir la réponse
Une étape contient une seule action, avec un verbe à l'impératif ou à l'infinitif : « Ouvrez le fichier ».
Si une étape en contient deux, le lecteur en oublie une, et quand elle échoue on ne sait pas laquelle des deux a posé problème.
Prérequis : de quoi s'agit-il ?
Voir la réponse
Ce qu'il faut avoir ou savoir avant de commencer : accès, droits, logiciel, version, sauvegarde.
Ils se placent avant la première étape : découvrir à la sixième qu'il fallait un droit administrateur oblige à tout recommencer.
Un collègue suit ta procédure de restauration et écrase la base de production : l'avertissement figurait après l'étape. Quelle correction ?
- Mettre l'avertissement avant l'étape, la sauvegarde en prérequis
- Mettre l'avertissement en gras et en rouge, juste après l'étape
- Ajouter un long paragraphe de contexte avant le début de la procédure
- Numéroter l'avertissement comme une étape à part, à la fin de la procédure
Voir la réponse
Mettre l'avertissement avant l'étape, la sauvegarde en prérequis
Le gras ne change pas l'ordre de lecture : l'étape est déjà faite quand on lit l'avertissement. Il faut le lire avant d'agir, et que la sauvegarde soit annoncée comme prérequis.