Passer au contenu principal
Cette page présente des choix stylistiques, des erreurs fréquentes 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 de rédaction 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. Parler d’une « API key » dans un paragraphe puis d’un « API token » dans le suivant rend le suivi difficile pour les utilisateurs.
  • Terminologie centrée sur le produit. Vos utilisateurs n’ont pas l’ensemble du contexte de votre produit. Utilisez un langage familier pour vos utilisateurs.
  • Expressions familières. En particulier pour la localisation, les expressions familières nuisent à la clarté.

​
Conseils pour appliquer un style cohérent

Appuyez-vous sur des guides de style existants pour standardiser votre documentation : Une fois les principes rédactionnels à adopter définis, automatisez au maximum. Vous pouvez utiliser des contrôles CI ou des analyseurs comme Vale.
Utilisez un workflow pour lancer un audit de style de manière planifiée ou à chaque fois que des modifications sont poussées vers votre dépôt de documentation, afin de corriger automatiquement les violations et de signaler ce qui nécessite une révision supplémentaire.

Types de contenu

Choisissez le type de contenu adapté à vos objectifs de documentation.

Accessibilité

Rendez votre documentation accessible à davantage d’utilisateurs.

Mettre le texte en forme

Découvrez les options de mise en forme et de style du texte.

Bonnes pratiques SEO

Améliorez la visibilité de votre documentation.