Faire écrire le mode d'emploi destiné à celui qui utilisera le produit

Quand l’employer

À employer quand une fonctionnalité est acceptée et va servir à quelqu'un d'autre que vous. À ne pas employer pour documenter le code : ce n'est pas le même lecteur ni le même document.

Les 4 trous à remplir avant d’envoyer

Chaque trou est une décision déjà prise. Un trou que vous ne savez pas remplir n’est pas une case à improviser : c’est un travail de cadrage qui manque.

{LECTEUR}

Qui lira ce document, et que sait-il déjà du métier et de l'outil ?

Pourquoi ce trou existe. Un mode d'emploi écrit sans lecteur en tête est écrit pour son auteur, et son auteur est le seul à ne pas en avoir besoin.

Si vous ne savez pas répondre. Nommez une personne réelle. Écrire pour une personne précise donne un texte utile à beaucoup ; écrire pour tout le monde donne un texte utile à personne.

{TACHES_A_COUVRIR}

Quelles tâches ce lecteur doit-il pouvoir accomplir seul après lecture ?

Pourquoi ce trou existe. Un document organisé par écran décrit l'outil ; un document organisé par tâche permet de travailler. Ce n'est pas la même utilité.

Si vous ne savez pas répondre. Écoutez les questions qu'on vous pose. Chaque question posée deux fois est une tâche à couvrir.

{ERREURS_FREQUENTES}

Quelles erreurs le lecteur fera-t-il, et comment s'en sortira-t-il ?

Pourquoi ce trou existe. Le passage le plus lu d'un mode d'emploi est celui qui explique comment se sortir d'une erreur, et c'est celui qu'on écrit en dernier ou pas du tout.

Si vous ne savez pas répondre. Regardez quelqu'un utiliser le produit pour la première fois sans l'aider. Notez chaque hésitation : ce sont vos erreurs fréquentes.

{CE_QUI_CHANGE_SOUVENT}

Quelles parties du produit changeront dans les mois qui viennent ?

Pourquoi ce trou existe. Un mode d'emploi qui décrit ce qui bouge devient faux, et un document faux est plus nuisible qu'un document absent.

Si vous ne savez pas répondre. Excluez du document tout ce qui n'est pas stabilisé, et dites-le : « cette partie change, demandez avant de vous y fier ».

Le corps du gabarit

Quatre parties, toujours dans cet ordre : le rôle et le mandat, le contexte factuel, la demande bornée, le format de sortie exigé. Les trous restent visibles à la copie, et c’est voulu : les remplir un par un est la dernière occasion de s’apercevoir qu’une décision manque.

## 1. RÔLE ET MANDAT

Tu es rédacteur technique. Ton mandat est d'écrire un mode d'emploi organisé par tâche, pour un lecteur nommé, qui doit pouvoir travailler seul après l'avoir lu. Tu n'écris pas de documentation de code et tu ne décris pas les écrans un par un.

## 2. CONTEXTE FACTUEL

Lecteur visé et ce qu'il sait déjà : {LECTEUR}
Tâches qu'il doit pouvoir accomplir seul : {TACHES_A_COUVRIR}
Erreurs qu'il fera : {ERREURS_FREQUENTES}
Parties du produit encore instables : {CE_QUI_CHANGE_SOUVENT}

Les parties instables ne sont pas documentées. Tu les cites dans une section unique qui dit qu'elles changent, et tu t'arrêtes là.

## 3. DEMANDE BORNÉE

Écris le mode d'emploi.

Ce que je veux :
1. une entrée par tâche, titrée par ce que le lecteur veut faire, dans ses mots à lui ;
2. pour chaque tâche : les étapes numérotées, avec les mots exacts visibles à l'écran ;
3. pour chaque tâche : à quoi le lecteur voit que c'est réussi ;
4. les erreurs fréquentes, chacune avec le message qu'il verra et la manière d'en sortir ;
5. la liste de ce qu'il ne peut pas faire seul, avec la personne à qui s'adresser ;
6. la section des parties instables, sans les documenter.

Ce que je ne veux pas : une description écran par écran, du vocabulaire technique non défini, une capture d'écran décrite au lieu du texte de l'écran, une tâche absente de ma liste.

## 4. FORMAT DE SORTIE EXIGÉ

Un titre de tâche formulé à l'infinitif, du point de vue du lecteur. Les mots visibles à l'écran sont écrits entre guillemets, exactement comme ils apparaissent. Chaque tâche tient en dix étapes au plus ; au-delà, tu la découpes en deux tâches.

Ta réponse est refusable si une section est organisée par écran plutôt que par tâche, si un terme technique apparaît sans définition, ou si une partie instable a été documentée malgré la consigne.

Ce que vous devez recevoir

• Une entrée par tâche, titrée à l'infinitif dans les mots du lecteur.
• Des étapes numérotées reprenant les mots exacts visibles à l'écran.
• Pour chaque tâche, le signe visible que c'est réussi.
• Les erreurs fréquentes, avec le message affiché et la manière d'en sortir.
• La liste de ce que le lecteur ne peut pas faire seul, avec l'interlocuteur.
• Une section listant les parties instables, non documentées.

Ce qui doit vous faire refuser

Ces motifs sont écrits comme des constats : « un fichier hors périmètre a été modifié » se vérifie, « le travail manque de rigueur » ne se vérifie pas.

• Le document est organisé par écran, donc il décrit l'outil au lieu de faire travailler.
• Un terme technique apparaît sans définition, ce qui arrête le lecteur à cette ligne.
• Les mots de l'écran sont paraphrasés au lieu d'être recopiés, et le lecteur ne les retrouve pas.
• Les erreurs fréquentes sont absentes, alors que c'est la partie la plus lue.
• Une partie instable a été documentée, ce qui produira une consigne fausse dans un mois.
• Une tâche demande plus de dix étapes sans être découpée.

Selon pour qui vous construisez

Pour mon employeur.

Faites tester le document par le lecteur visé, sans vous, et notez où il s'arrête. Chaque arrêt est une étape mal écrite, jamais un défaut du lecteur.

Pour un client.

Le mode d'emploi conditionne la fin de la mission : sans lui, le client vous rappelle pour chaque question, et vous travaillez gratuitement.