Passer au contenu principal
Une bonne documentation technique a une seule mission : aider les utilisateurs à atteindre un objectif et retourner à leur travail. Les choix de style et de ton soutiennent cet objectif ou s’y opposent. Une rédaction claire et cohérente renforce la confiance des utilisateurs. Une rédaction incohérente ou peu claire crée des frictions et érode la confiance envers votre produit. Ce guide couvre les principes fondamentaux d’une rédaction technique efficace, avec des conseils pratiques sur la façon de les appliquer.

​
Rédigez à la deuxième personne

Adressez-vous directement aux utilisateurs en les tutoyant ou en utilisant “vous”. La deuxième personne rend les instructions plus faciles à suivre et maintient l’attention sur ce que les utilisateurs font plutôt que sur ce que le produit fait. 
<!-- Deuxième personne (préféré) -->
Vous pouvez configurer le délai d'expiration dans votre fichier de paramètres.

<!-- Troisième personne (à éviter) -->
Les utilisateurs peuvent configurer le délai d'expiration dans le fichier de paramètres.
La deuxième personne aide également à détecter la voix passive : lorsque vous écrivez “vous”, vous êtes obligé de dire qui fait quoi.

​
Utilisez la voix active

La voix active rend les phrases plus courtes et plus claires. À la voix passive, le sujet reçoit l’action. À la voix active, le sujet la réalise. 
<!-- Active -->
L'API renvoie une erreur lorsque le token expire.

<!-- Passive -->
Une erreur est renvoyée lorsque le token a expiré.
La voix passive n’est pas toujours incorrecte. Elle est appropriée lorsque l’acteur est inconnu ou sans importance. Mais la voix passive comme habitude par défaut rend la documentation plus difficile à lire. Un test rapide : si vous pouvez ajouter “par des zombies” après le verbe, la phrase est passive. “Une erreur est renvoyée [par des zombies]” est passive. “L’API renvoie [par des zombies] une erreur” est active.

​
Gardez les phrases et les paragraphes courts

La documentation est parcourue plus qu’elle n’est lue. Les longues phrases et les paragraphes denses ralentissent les utilisateurs lorsqu’ils cherchent une réponse spécifique. Recommandations :
  • Visez des phrases de moins de 25 mots
  • Une idée par phrase
  • Deux à quatre phrases par paragraphe
  • Découpez les listes d’étapes en séquences numérotées, pas en prose continue
Si une phrase nécessite plusieurs virgules ou points-virgules pour tenir ensemble, elle peut probablement être divisée en deux phrases.

​
Utilisez des titres qui correspondent à l’intention de l’utilisateur

Les titres organisent la page pour les humains et les moteurs de recherche. Rédigez-les pour répondre à la question qu’un utilisateur pourrait se poser, pas pour étiqueter un sujet du point de vue du produit. 
<!-- Orienté intention (mieux) -->
## Comment configurer l'authentification

<!-- Étiquette de sujet (plus faible) -->
## Configuration de l'authentification
Utilisez la casse de phrase pour tous les titres (“Premiers pas”, pas “Premiers Pas”). Ne sautez pas de niveaux de titre—passez de H2 à H3, pas de H2 à H4. Dans la documentation Mintlify, le H1 de la page est généré automatiquement à partir de la propriété title: du frontmatter. N’ajoutez pas de H1 manuel dans le corps.

​
Utilisez une terminologie cohérente

Choisissez un terme pour chaque concept et utilisez-le partout. Alterner entre “API key”, “API token” et “access token” pour décrire la même chose oblige les utilisateurs à s’arrêter et se demander si vous parlez de la même chose. Lorsque vous introduisez un terme pour la première fois, définissez-le sur place plutôt que de renvoyer vers une autre page. 
<!-- Définir en contexte -->
Chaque requête nécessite une API key—un token unique qui identifie votre compte.

<!-- Ne présumez pas de connaissances préalables -->
Chaque requête nécessite une API key.
Si votre produit a des noms spécifiques pour les choses (objets, actions, éléments d’interface), utilisez ces noms exactement tels qu’ils apparaissent dans le produit. Mettez-les en majuscules de manière cohérente.

​
Calibrez le ton en fonction de votre audience et du type de contenu

Le ton doit correspondre à ce que les utilisateurs essaient de faire. Un guide de démarrage pour les nouveaux utilisateurs bénéficie d’un ton plus chaleureux et encourageant. Une référence d’API pour les développeurs expérimentés bénéficie de la densité et de la précision plutôt que de la chaleur. Quelques principes qui s’appliquent à tous les types de contenu :
  • Soyez direct sans être brusque. “Cliquez sur Enregistrer” est mieux que “Veuillez cliquer sur le bouton Enregistrer lorsque vous êtes prêt à continuer.”
  • Évitez les phrases de remplissage. “Il convient de noter que”, “Afin de”, “Veuillez noter que” et “Simplement” ajoutent des mots sans ajouter de sens.
  • Ne donnez pas d’avis. “C’est une fonctionnalité puissante” est une opinion. Documentez ce qu’elle fait, pas à quel point elle est impressionnante.
  • Utilisez le vocabulaire de vos utilisateurs. Si vos utilisateurs appellent cela un “webhook”, ne l’appelez pas “event callback” dans la documentation. Utilisez le mot qu’ils recherchent déjà.

​
Évitez les erreurs courantes

​
Jargon et terminologie interne

Les équipes développent un langage abrégé que les utilisateurs ne rencontrent jamais. Examinez le nouveau contenu pour repérer les termes qui seraient inconnus pour quelqu’un qui découvre votre produit pour la première fois.

​
Capitalisation incohérente

Décidez si les noms des fonctionnalités de votre produit prennent une majuscule (“le Dashboard”, “l’API Explorer”) et appliquez-le de manière cohérente. Une capitalisation incohérente signale un manque d’attention aux détails.

​
Expressions familières

Les expressions informelles et les idiomes sont plus difficiles à traduire et plus difficiles à comprendre pour les locuteurs non natifs. La documentation qui s’adresse à un public international bénéficie d’un langage simple et direct.

​
Fautes d’orthographe et de grammaire

Même quelques erreurs réduisent la crédibilité. Elles signalent que le contenu n’a pas été relu attentivement, ce qui amène les utilisateurs à se demander si le contenu technique est tout aussi peu fiable.

​
Appliquez les normes avec des outils

Les principes de rédaction ne perdurent que s’ils font partie d’un flux de travail reproductible. Quelques façons d’automatiser leur application :
  • Vale : Un linter pour la prose qui vérifie contre des règles de style configurables. Vous pouvez écrire des règles qui appliquent votre propre terminologie, signalent la voix passive ou détectent les erreurs courantes.
  • Vérifications CI : Exécutez Vale ou d’autres linters sur chaque pull request afin que les problèmes de style soient détectés avant la fusion du contenu.
  • Guides de style existants : Plutôt que d’écrire des règles à partir de zéro, commencez par un guide établi. Le Google Developer Documentation Style Guide, le Microsoft Style Guide et le Splunk Style Guide sont tous gratuits et largement utilisés.
Utilisez un workflow pour exécuter un audit de style selon un calendrier ou chaque fois que des modifications sont poussées vers votre dépôt de documentation.

​
Questions fréquemment posées

Adaptez la formalité à votre audience et au contexte du produit. Les outils pour développeurs peuvent être directs et concis—passez les politesses et allez droit au code. La documentation pour des utilisateurs moins techniques ou des produits d’entreprise bénéficie souvent d’un ton plus chaleureux qui anticipe la confusion. Dans tous les cas, évitez le langage corporatif rigide. “Utiliser” n’apporte pas plus de précision que “employer”. Écrivez comme un collègue compétent expliquerait quelque chose, pas comme un document juridique le décrirait.
Lorsque l’acteur est inconnu, non pertinent, ou lorsque mettre en valeur le résultat est plus important que celui qui le cause. “La requête est validée avant le traitement” est correct si vous décrivez ce qui arrive à une requête, pas qui la valide. La voix passive devient problématique lorsqu’elle masque qui est responsable d’une action que l’utilisateur doit effectuer.
Identifiez le public principal de chaque page et écrivez pour lui. Un guide de démarrage doit supposer un minimum de connaissances préalables. Une référence d’API doit supposer que le lecteur sait comment fonctionnent les APIs. L’erreur est d’essayer de servir les deux sur la même page—ajouter du contexte pour débutants sur une page de référence ralentit les experts, et supposer des connaissances d’expert dans un tutoriel perd les débutants. Si vous avez réellement deux publics distincts, envisagez des types de contenu séparés pour chacun. Consultez Types de contenu pour des conseils.
Maintenez une liste de terminologie—un simple tableau de termes préférés et de termes à éviter. Partagez-la avec tous ceux qui contribuent à la documentation et vérifiez-la lors de la révision. Vale peut l’appliquer automatiquement avec un fichier de vocabulaire personnalisé. L’investissement dans le maintien d’une liste est rapidement rentabilisé par la réduction des cycles de révision et la diminution des plaintes des utilisateurs concernant une terminologie confuse.
Assez longue pour couvrir le sujet complètement, assez courte pour rester concentrée. Si une page couvre deux tâches distinctes, envisagez de la diviser. Si elle couvre une tâche mais que le contenu est mince, il manque peut-être des détails importants. Le contenu de référence peut être long et dense—les utilisateurs le parcourent. Le contenu conceptuel doit être plus court—les utilisateurs le lisent. Consultez Types de contenu pour en savoir plus sur l’adaptation de la longueur de la page à l’objectif du contenu.

Types de contenu

Choisissez le bon type de contenu pour vos objectifs de documentation.

Accessibilité

Rendez votre documentation accessible à davantage d’utilisateurs.

Mise en forme du texte

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

Bonnes pratiques SEO

Améliorez la découvrabilité de la documentation.