Documentation orientée utilisateur

Écrivez pour la personne qui utilise l'outil, pas pour celle qui l'a construit.

« Utilisateur » désigne quiconque l'utilise. Pour une appli, c'est l'utilisateur final. Pour une bibliothèque, c'est le développeur qui l'installe. Dans les deux cas, ce ne sont pas eux qui l'implémentent, et la documentation doit le refléter.

Ton

De l'anglais courant — la façon dont tu l'expliquerais à un collègue assis à côté de toi. La formalité n'ajoute pas d'autorité, elle ajoute juste de la distance et des mots.

• Deuxième personne, actif, présent. « Tu appuies sur Enregistrer », pas « le bouton Enregistrer devrait être appuyé » ou « l'utilisateur pourra ensuite enregistrer ».
• Supprime « juste », « simplement », « facile », « évidemment ». Ça n'ajoute rien quand ça marche, et ça sonne comme de la moquerie quand ça ne marche pas.
• Pas d'adjectifs marketing. « Puissant », « fluide », « robuste », « intuitif » — c'est l'auteur qui admire le produit. Le lecteur est en pleine tâche et s'en fout.
• Un terme par concept, en accord avec l'UI exactement. Si le bouton dit Workspace, la doc ne dit jamais « projet » ou « espace équipe ». Varier le vocabulaire, c'est de la bonne prose et de la mauvaise documentation — chaque synonyme se lit comme un concept nouveau.

Périmètre : ce qui rentre dedans

Inclus seulement ce que le lecteur doit savoir pour utiliser l'outil. Par défaut, tu laisses les choses dehors.

Les détails d'implémentation restent dehors. Pas la base de données, la queue, le framework, le nom de l'algorithme, le service interne, la refonte qu'il a fallu faire pour livrer. Le test ce n'est pas « c'est technique ? » — c'est « le lecteur sera-t-il surpris, ou fera-t-il une mauvaise décision, sans ça ? »

Le comportement observable passe ce test même quand ça sonne technique, et belongs dans la doc : les rate limits, le comportement hors ligne, ce qui synce et quand, où les fichiers sont stockés, ce qui se passe en cas de conflit, ce qui survit à une réinstallation. La mécanique qui produit ce comportement, non.

Concis signifie pas de remplissage, pas court. Chaque phrase justifie sa place. Une section dépannage complète est encore concise si aucune n'est du padding — et une page de deux lignes est gonflée si une ligne est un message de bienvenue. Coupe les préambules, les reformulations du titre, et « dans cet article tu apprendras ».

Structure

• Organise par objectif utilisateur, pas par fonctionnalité ou écran. Les titres sont des choses que les gens veulent faire — « Partager un rapport avec quelqu'un en dehors de ton équipe » — pas des noms comme « Module de partage ».
• Commence par le résultat, puis les étapes. Les gens ont besoin de savoir qu'ils sont sur la bonne page avant d'investir dans l'étape 1.
• Prérequis et limites en avant. Plan requis, permission, plateforme, limite de taille de fichier. Découvrir le blocage à l'étape 6, c'est le pire moment possible.
• Une page répond à une question, et fonctionne seule. La plupart des lecteurs arrivent par la recherche ou un lien direct, jamais de la page 1. Suppose que personne n'a lu la page précédente ; fais des liens au lieu de supposer.
• Choisis un chemin. Où trois façons existent, documente la recommandée. Les alternatives reçoivent une courte note à la fin, ou rien.

Couvre le chemin malheureux

C'est la section la plus sautée et celle que les gens cherchent vraiment.

• Documente les cas d'échec : ce que dit l'erreur, ce qui la cause, quoi faire ensuite.
• Dis ce que la fonctionnalité ne fait pas quand les utilisateurs supposent prévisiblement qu'elle le fait. Moins cher qu'un ticket support.
• Avertis avant les actions destructrices, jamais après. L'avertissement va au-dessus de l'étape à laquelle il s'applique.

Évite qu'elle ne pourrisse

• Des exemples vrais avec des données qui ressemblent à du vrai. Pas de foo, pas de test123, pas de lorem ipsum. Les exemples devraient être copiables et produire le résultat montré.
• Pas de langage relatif au temps. « Nouveau », « récemment », « actuellement », « bientôt » — tout pourrit silencieusement. Pareil pour les promesses de roadmap.
• Parcours chaque procédure littéralement. Si quelqu'un la suit mot pour mot ne peut pas finir, le doc est faux — pas le lecteur.

Avant de publier

Lis le brouillon une fois en cherchant seulement ces points :

1. Quelque chose que le lecteur n'a pas besoin pour terminer la tâche → supprime-le.
2. Quelque chose sur le fonctionnement interne → supprime-le, sauf si le comportement en dépend.
3. Une phrase que tu ne dirais pas à voix haute → réécris-la.
4. Ce qui se passe quand ça tourne mal → c'est répondu ?