Une documentation utilisateur répond à une tâche réelle, montre les conditions nécessaires et indique le résultat attendu après l’action.
Une liste de boutons ne remplace pas une procédure. L’utilisateur cherche souvent à traiter un cas particulier : corriger un devis, exporter une période ou reprendre une demande bloquée. La page doit commencer par cette action et signaler les limites.
Écrire pour un rôle
Un commercial et un administrateur n’ont pas les mêmes droits ni le même vocabulaire. Indiquez le rôle concerné et évitez de présenter une action inaccessible comme une étape obligatoire. Les matrices de permissions rendent ces différences vérifiables.
Montrer les prérequis
Expliquez les données nécessaires, l’état du dossier et le droit requis. Une capture d’écran ne doit pas contenir un vrai client ou un montant confidentiel. Utilisez un exemple identifiable comme démonstration.
Décrire les erreurs
Ajoutez les causes courantes et l’action suivante. Distinguez une donnée invalide, un accès refusé, une tâche en attente et une panne temporaire. Le suivi des erreurs doit fournir l’identifiant de diagnostic mentionné dans la procédure.
Maintenir le contenu
Chaque page possède un propriétaire et une date de revue. Mettez à jour la documentation avec une modification d’interface ou de règle. Une page ancienne peut être plus dangereuse qu’une page absente si elle conseille une action incorrecte.
Vérifier avec les utilisateurs
Demandez à une personne de suivre la procédure sans explication orale. Notez l’endroit où elle hésite et corrigez le texte. La documentation doit rester consultable depuis l’écran où l’utilisateur travaille.
Sources : Microsoft, documentation utilisateur, W3C, contenu accessible.
Adapter les formats
Les procédures doivent être lisibles sur un écran étroit et compatibles avec le clavier. Les tableaux longs peuvent proposer une version structurée et un résumé. Une vidéo peut compléter le texte, mais elle ne doit pas être l’unique source d’une étape ou d’une règle.
Traduisez les pages réellement utilisées et conservez le même vocabulaire que l’interface. Une traduction incomplète doit être signalée plutôt que de mélanger des termes qui désignent deux états différents. Le propriétaire vérifie les textes après chaque changement de libellé.
Garder les procédures vérifiables
Un exemple de procédure doit préciser le compte de test, l’état initial et la sortie attendue. Une capture seule ne prouve pas que le bouton fonctionne ou que le rôle peut l’utiliser. Reliez les passages sensibles aux critères de recette et aux messages affichés par le produit.
Les pages qui décrivent les exports, les imports ou les restaurations doivent expliquer la durée du traitement, le rapport d’erreur et la procédure après un échec. Les utilisateurs doivent savoir quand attendre et quand contacter le support. Cette précision évite les répétitions et les manipulations de fichiers non contrôlées.
Ajoutez une date de revue et un lien pour signaler une procédure incorrecte. Le support peut ainsi corriger rapidement une page après une modification du produit. Une documentation reliée à la version et au rôle reste plus facile à maintenir qu’un guide général qui mélange tous les parcours.
Organiser les pages
Une page doit avoir une adresse stable, un titre précis et un lien depuis l’écran concerné. Regroupez les procédures par tâche plutôt que par équipe technique. Une recherche interne doit retrouver les termes employés par les utilisateurs et les noms affichés dans l’interface.
Conservez un court résumé au début, puis les prérequis, les étapes, les résultats et les problèmes courants. Une personne pressée doit pouvoir identifier rapidement si la page correspond à son cas. Les détails secondaires peuvent être ouverts ensuite ou placés dans une référence séparée.
Documenter les changements
Lorsqu’une fonctionnalité change, indiquez la nouvelle action et la date d’application. Ne demandez pas au lecteur de comparer deux versions pour savoir quoi faire. Une page de migration peut expliquer le changement, tandis que la procédure courante doit décrire l’état actuel.
Le propriétaire de la page vérifie les captures, les liens et les permissions. Utilisez des images sans données réelles et ajoutez un texte alternatif utile. Une capture ne doit pas être la seule manière de comprendre une étape.
Répondre aux cas de panne
Ajoutez la procédure lorsque l’export échoue, qu’un import est en attente ou qu’une notification n’arrive pas. Indiquez l’identifiant à fournir au support et les informations qu’il est prudent de ne pas copier dans un ticket. Les tâches planifiées et leur état doivent être expliqués avec les mots de l’équipe.
Mesurer la compréhension
Analysez les recherches sans résultat, les pages abandonnées et les liens vers le support. Demandez ponctuellement à un utilisateur de suivre la procédure avec un compte de test. Ne déduisez pas qu’une page est utile parce qu’elle reçoit beaucoup de visites : elle peut être consultée parce qu’elle est confuse.
Une documentation maintenue réduit les décisions répétées et rend les changements plus faciles à adopter. Elle doit rester proche du produit, avec une responsabilité claire et une revue déclenchée par chaque modification importante.