Rédaction technique

Documentation écrite à partir du produit, pas du cahier des charges

La plupart des mauvaises documentations ont été rédigées à partir d'un cahier des charges ou de la mémoire d'un développeur. Elles décrivent comment la fonctionnalité était censée fonctionner, pas l'écran que l'utilisateur voit réellement, avec son bouton renommé et son étape de confirmation supplémentaire. L'utilisateur suit l'étape quatre, ne trouve rien qui corresponde et ouvre un ticket.

Nous exécutons chaque procédure du produit avant de la rédiger, sur un compte de test, dans le rôle que le lecteur aura. Lorsqu'une étape se comporte différemment de ce que l'équipe attend, nous la consignons, car le travail de documentation fait régulièrement remonter des bugs que personne n'avait signalés. Cette liste s'avère souvent aussi précieuse que la documentation.

Séparer la tâche de l'explication

Un utilisateur qui cherche à exporter une facture ne veut pas d'abord trois paragraphes sur le modèle de facturation. Un utilisateur qui cherche à comprendre le modèle de facturation ne veut pas d'une liste numérotée de clics. Mélanger les deux dans un même article rend la recherche plus difficile et la lecture plus lente.

Nous répartissons le contenu en tâches (comment faire une chose), concepts (comment quelque chose fonctionne et pourquoi) et référence (réglages, champs, limites, codes d'erreur). Chaque type a son propre modèle, les pages restent donc cohérentes après notre transmission, quand votre équipe ajoute le quarantième article.

La liste terminologique est ce qui maintient la cohérence de l'ensemble dans le temps. Si l'interface dit « espace de travail », la documentation ne dit jamais « projet » ou « compte » pour la même chose. C'est un petit document qui évite la plupart des confusions signalées par les utilisateurs.

• Articles de tâche : un objectif, des étapes numérotées, le résultat que l'utilisateur doit voir
• Articles de fond : le modèle derrière une fonctionnalité, avec un schéma quand cela aide
• Pages de référence : chaque champ, paramètre et limite, dans un tableau facile à parcourir
• Dépannage : le message d'erreur tel quel, sa cause et la correction