Que fait Étapes de quart de nuit ?
Ce que c'est
La plupart des procédures sont écrites par la personne qui connaît déjà le travail. Elles se lisent bien à un bureau. Elles échouent à 3 h du matin, dans une pièce bruyante, sur un téléphone, dans une langue seconde, ou lorsque le lecteur a peur de casser quelque chose. Les échecs sont prévisibles : deux actions cachées dans une étape, un avertissement qui se trouve après l'étape qu'il protège, une condition qui arrive à la fin de la phrase, une phrase passive qui cache qui doit agir, et des mots comme « correctement » qui demandent au lecteur de deviner.
Cette compétence transforme un tel texte en étapes qu'une personne peut suivre à la lettre. Elle emprunte la discipline des langages contrôlés utilisés dans la maintenance aéronautique et industrielle (phrases courtes, une action par phrase, voix active, un mot pour une chose), l'ordre des messages de sécurité utilisé sur les étiquettes des équipements (mot d'avertissement, danger, conséquence, action d'évitement), et l'habitude d'écrire un résultat attendu après chaque étape risquée pour que le lecteur sache quand s'arrêter.
Ce n'est pas un passage « pour rendre le texte plus humain ». L'objectif est une procédure qui ne peut pas être mal lue, même si elle semble un peu plate.
Quand l'utiliser
- Runbooks, playbooks d'incident, listes de contrôle d'astreinte, étapes de déploiement et de restauration.
- Guides d'installation ou de réparation pour le matériel, les appareils domestiques, l'équipement de laboratoire ou l'informatique de bureau.
- Procédures opérationnelles standard (SOP) et notes de passation pour une autre personne ou un autre quart.
- Instructions qui seront traduites automatiquement ou lues par des locuteurs non natifs.
- Tout texte où une seule étape mal lue peut entraîner une perte de données, d'argent ou provoquer des blessures.
Ne l'utilisez pas pour des essais, des textes marketing ou des explications conceptuelles. Ceux-ci nécessitent une voix différente.
Les règles (niveau par défaut)
| # | Règle | Limite ou test |
|---|---|---|
| R1 | Une action par étape | Pas de « , puis », « et puis », « ; » ou deux verbes joints par « et » dans une étape |
| R2 | Phrases d'instruction courtes | 20 mots en anglais, environ 35 caractères en chinois |
| R3 | Phrases descriptives courtes | 25 mots en anglais, environ 45 caractères en chinois |
| R4 | Impératif, voix active | Commencez par le verbe. Nommez l'acteur s'il ne s'agit pas du lecteur |
| R5 | Condition en premier | « Si le voyant est rouge, arrêtez-vous. » jamais « Arrêtez-vous si le voyant est rouge. » |
| R6 | Un mot, un sens | Verrouillez les termes dans un glossaire. Ne remplacez jamais les synonymes pour varier |
| R7 | Valeurs exactes | Nombres avec unités, libellés exactement comme ils apparaissent à l'écran ou sur l'appareil |
| R8 | Message de sécurité avant l'étape | Mot d'avertissement, danger, conséquence, quoi faire |
| R9 | Résultat attendu après les étapes risquées | « Résultat : ... » et quoi faire si le résultat est différent |
| R10 | Pas de mots de devinette | Supprimez « correctement », « au besoin », « assurez-vous », « devrait », « simplement » |
Niveau strict (pour les textes critiques pour la sécurité ou réglementés) : appliquez chaque règle sans exception, n'autorisez aucune atténuation et mettez une ligne de résultat après chaque étape. Niveau léger (pour une note interne déjà correcte) : appliquez uniquement R1, R5, R8 et R9.
Mots d'avertissement
Utilisez le mot le plus bas qui soit encore vrai. N'exagérez pas.
- DANGER : provoque la mort ou des blessures graves s'il est ignoré.
- AVERTISSEMENT : peut provoquer la mort, des blessures graves ou la perte de données ou d'argent importants.
- ATTENTION : peut provoquer des blessures mineures ou des dommages que vous pouvez réparer.
- AVIS : aucun risque de blessure ; seulement un risque pour les biens, les données ou le temps.
Chaque message de sécurité comporte trois parties : quel est le danger, ce qui se produit si le lecteur l'ignore et quoi faire. « Faites attention » n'est pas un message de sécurité.
Comment travailler
- Remplissez la fiche de procédure. Avant de modifier, écrivez : l'état cible (« Disque 2 en reconstruction »), qui va la suivre (rôle, langue, conditions telles que gants, bruit, écran de téléphone, nuit), ce qu'ils ont (accès, outils, temps), les dangers et les conditions d'arrêt. Demandez à l'utilisateur tout ce que vous ne pouvez pas déduire. Une condition d'arrêt manquante est la lacune la plus courante.
- Listez les faits que vous devez conserver. Chaque nombre, unité, libellé, commande, contrainte d'ordre, avertissement et condition. La réécriture doit tous les contenir et n'en ajouter aucun. Si vous pensez qu'une valeur est erronée, signalez-la ; ne la corrigez pas en silence.
- Divisez en actions. Un verbe que le lecteur effectue = une étape. La navigation compte (« Aller dans Stockage » et « Sélectionner Disque 2 » sont deux étapes). Placez le contexte dans un court paragraphe « Avant de commencer ».
- Réécrivez chaque étape. Verbe en premier, condition en premier, libellés exacts en gras ou
code, unités toujours. Remplacez tout passif qui cache un acteur : « La clé est générée » devient « L'outil génère la clé » ou, mieux, l'étape que le lecteur effectue pour la générer. - Placez les messages de sécurité. Pour chaque étape qui supprime, écrase, éteint, redémarre, déconnecte, chauffe, coupe ou met sous pression, placez le message directement au-dessus de l'étape. Choisissez le mot d'avertissement dans l'échelle ci-dessus.
- Ajoutez les résultats et les sorties. Après chaque étape risquée ou modifiant l'état, écrivez ce que le lecteur voit lorsqu'elle a fonctionné. Si le résultat peut différer, donnez une ligne : « Si vous voyez X, arrêtez-vous et allez à la section Récupération A. » Rédigez les sections de récupération.
- Verrouillez le glossaire. Choisissez un terme par chose (par exemple « tiroir », pas « cage » ni « chariot »). Enregistrez-le sous
glossary.jsonsi la procédure doit être maintenue. - Exécutez le linter. Exécutez
python scripts/stepcheck.py lint procedure.md --glossary glossary.json. Corrigez chaque constat UNSAFE et REWORK, ou expliquez pourquoi il s'agit d'un faux positif. - Effectuez une simulation littérale. Lisez uniquement les étapes numérotées, comme quelqu'un qui fait exactement ce que chaque phrase dit et rien de plus. Où s'arrêteraient-ils, devineraient-ils ou feraient-ils quelque chose de nuisible ? Corrigez ces endroits.
- Retournez la procédure réécrite, puis une courte liste de modifications (numéros de règle), la liste des faits que vous n'avez pas pu vérifier et les questions ouvertes.
Le script d'aide
scripts/stepcheck.py est un linter Python de la bibliothèque standard pour les procédures Markdown, en anglais ou en chinois.
| Code | Gravité | Signification |
|---|---|---|
| HAZARD-NO-WARNING | dur | Une étape risquée n'a pas de message de sécurité au-dessus d'elle |
| LATE-WARNING | dur | Le message de sécurité se trouve après l'étape qu'il protège |
| WEAK-WARNING | corriger | Le message ne dit pas ce qui se produit |
| LONG | corriger | Phrase d'instruction au-dessus de la limite |
| STACKED | corriger | Plus d'une action dans une étape |
| HIDDEN-ACTOR | corriger | La voix passive ou 被 cache qui agit |
| HEDGE / VAGUE | corriger | Mots de devinette |
| CONDITION-LAST | corriger | La condition vient après l'action |
| DRIFT | corriger | Un synonyme interdit du glossaire |
| NO-RESULT, LONG-DESC | note | Conseil uniquement |
Verdict : READY (code de sortie 0), REWORK (code de sortie 1), UNSAFE (code de sortie 2). Le script utilise des listes de mots et des motifs, donc il manque des choses et signale parfois une phrase correcte. Il ne remplace jamais l'étape 9.
Exemple
Avant :
- Éteignez le NAS s'il est encore allumé.
- Retirez le tiroir du disque 2 et insérez le nouveau disque dedans. ATTENTION : Le vieux disque peut être chaud.
Après :
AVERTISSEMENT : Éteignez le NAS avant de retirer un disque. Un disque retiré pendant qu'il tourne peut corrompre le second disque. 5. Maintenez le bouton d'alimentation enfoncé pendant 2 secondes pour éteindre le NAS. Résultat : Tous les voyants à l'avant s'éteignent après environ 1 minute. ATTENTION : Le vieux disque peut être chaud après utilisation. Tenez-le par le tiroir, ou vous pouvez vous brûler les doigts. 6. Retirez le tiroir du disque 2. 7. Insérez le nouveau disque dans le tiroir.
Modifications : R1 (étape 4 divisée), R5 (condition supprimée en faisant de l'extinction une étape distincte), R8 (avertissement déplacé vers le haut et pourvu d'une conséquence), R9 (résultat ajouté). Les fichiers complets se trouvent dans examples/.
Conseils
- Si le texte source est erroné, la réécriture la plus claire reste erronée. Signalez les valeurs douteuses dans la liste des modifications.
- Conservez les commandes, les chemins et les libellés à l'écran octet par octet. Un texte clair autour d'une commande mal orthographiée est pire que l'original.
- Une étape qui nécessite une longue explication est généralement deux étapes plus une note avant elles.
- Numérotez les étapes en continu. Ne recommencez pas la numérotation à l'intérieur d'une procédure ; utilisez des sections distinctes pour la récupération.
- Lisez les versions chinoise et anglaise côte à côte lorsque vous les produisez toutes les deux : chaque étape doit se correspondre une à une.
- Ne prétendez jamais que la sortie est conforme à une norme de langage contrôlé officielle. Dites « rédigé dans un style contrôlé ».