Cette page présente les choix stylistiques, les erreurs courantes et des conseils pratiques pour rédiger une documentation technique.
Principes de rédaction
- Soyez concis. Les lecteurs consultent la documentation pour atteindre un objectif. Allez droit au but.
- La clarté plutôt que l’ingéniosité. Soyez simple, direct et évitez le jargon ou les phrases trop complexes.
- Utilisez la voix active. Plutôt que « Un fichier de configuration devrait être créé », écrivez « Créez un fichier de configuration ».
- Rendez le contenu scannable. Utilisez des titres pour orienter les lecteurs. Scindez les paragraphes denses. Préférez les listes à puces pour faciliter le survol.
- Rédigez à la deuxième personne. Vous adresser au lecteur facilite le suivi des instructions et rend la documentation plus personnelle.
Erreurs d’écriture courantes
- Fautes d’orthographe et de grammaire. Même quelques fautes d’orthographe et de grammaire dans votre documentation la rendent moins crédible et plus difficile à lire.
- Terminologie incohérente. Appeler un élément « clé d’API » dans un paragraphe puis « jeton d’API » dans le suivant rend la lecture difficile pour les utilisateurs.
- Terminologie centrée sur le produit. Vos utilisateurs n’ont pas l’intégralité du contexte de votre produit. Utilisez un langage qui leur est familier.
- Colloquialismes. Surtout en contexte de localisation, les tournures familières nuisent à la clarté.