> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Comment rédiger une documentation technique

> Rédigez une doc technique claire et cohérente : conseils pratiques sur la voix, la structure, la terminologie et le ton pour la doc développeurs et produit.

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.

<div id="write-in-second-person">
  ## Rédigez à la deuxième personne
</div>

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.

```mdx theme={null}
<!-- 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.

<div id="use-active-voice">
  ## Utilisez la voix active
</div>

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.

```mdx theme={null}
<!-- 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.

<div id="keep-sentences-and-paragraphs-short">
  ## Gardez les phrases et les paragraphes courts
</div>

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.

<div id="use-headings-that-match-user-intent">
  ## Utilisez des titres qui correspondent à l'intention de l'utilisateur
</div>

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.

```mdx theme={null}
<!-- 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.

<div id="use-consistent-terminology">
  ## Utilisez une terminologie cohérente
</div>

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.

```mdx theme={null}
<!-- 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.

<div id="calibrate-tone-to-your-audience-and-content-type">
  ## Calibrez le ton en fonction de votre audience et du type de contenu
</div>

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à.

<div id="avoid-common-mistakes">
  ## Évitez les erreurs courantes
</div>

<div id="jargon-and-internal-terminology">
  ### Jargon et terminologie interne
</div>

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.

<div id="inconsistent-capitalization">
  ### Capitalisation incohérente
</div>

Décidez si vous mettez en majuscule les noms des fonctionnalités de votre produit ("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.

<div id="colloquialisms">
  ### Expressions familières
</div>

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.

<div id="spelling-and-grammar-errors">
  ### Fautes d'orthographe et de grammaire
</div>

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

<div id="enforce-standards-with-tooling">
  ## Appliquez les normes avec des outils
</div>

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](https://vale.sh) :** 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](/fr/deploy/ci) :** Exécutez Vale ou d'autres linters sur chaque pull request pour détecter les problèmes de style 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](https://developers.google.com/style), le [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) et le [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse) sont tous gratuits et largement utilisés.

<Tip>
  Utilisez une [automatisation](/fr/automations) 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.
</Tip>

<div id="frequently-asked-questions">
  ## Questions fréquemment posées
</div>

<AccordionGroup>
  <Accordion title="Quel niveau de formalité pour une documentation technique ?">
    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.
  </Accordion>

  <Accordion title="Quand la voix passive est-elle acceptable ?">
    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.
  </Accordion>

  <Accordion title="Dois-je écrire pour les débutants ou les experts ?">
    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](/fr/guides/content-types) pour des conseils.
  </Accordion>

  <Accordion title="Comment maintenir une terminologie cohérente sur un grand site de documentation ?">
    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.
  </Accordion>

  <Accordion title="Quelle est la bonne longueur pour une page de documentation ?">
    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](/fr/guides/content-types) pour en savoir plus sur l'adaptation de la longueur de la page à l'objectif du contenu.
  </Accordion>
</AccordionGroup>

<div id="related-pages">
  ## Pages associées
</div>

<CardGroup cols={2}>
  <Card title="Types de contenu" icon="folder-tree" href="/fr/guides/content-types">
    Choisissez le bon type de contenu pour vos objectifs de documentation.
  </Card>

  <Card title="Accessibilité" icon="person-standing" href="/fr/guides/accessibility">
    Rendez votre documentation accessible à davantage d'utilisateurs.
  </Card>

  <Card title="Mise en forme du texte" icon="case-sensitive" href="/fr/create/text">
    Découvrez les options de mise en forme et de style du texte.
  </Card>

  <Card title="Bonnes pratiques SEO" icon="search" href="/fr/guides/seo">
    Améliorez la découvrabilité de la documentation.
  </Card>
</CardGroup>


## Related topics

- [Comment créer une documentation accessible](/fr/guides/accessibility.md)
- [Comment configurer une documentation multilingue](/fr/guides/internationalization.md)
- [Comment comprendre l'audience de votre documentation](/fr/guides/understand-your-audience.md)