mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
866e1e508a
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
66 lines
3.4 KiB
Plaintext
66 lines
3.4 KiB
Plaintext
---
|
||
title: "Style et ton"
|
||
description: "Rédigez une documentation technique efficace avec un style cohérent."
|
||
keywords: ["writing principles", "active voice", "technical writing", "style guides"]
|
||
---
|
||
|
||
<Tip>
|
||
Cette page présente des choix stylistiques, des erreurs fréquentes et des conseils pratiques pour rédiger une documentation technique.
|
||
</Tip>
|
||
|
||
<div id="writing-principles">
|
||
## Principes de rédaction
|
||
</div>
|
||
|
||
* **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.
|
||
|
||
<div id="common-writing-mistakes">
|
||
## Erreurs de rédaction courantes
|
||
</div>
|
||
|
||
- **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é.
|
||
|
||
<div id="tips-for-enforcing-style">
|
||
## Conseils pour appliquer un style cohérent
|
||
</div>
|
||
|
||
Appuyez-vous sur des guides de style existants pour standardiser votre documentation :
|
||
|
||
* [Microsoft Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
|
||
* [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)
|
||
* [Google Developer Documentation Style Guide](https://developers.google.com/style)
|
||
|
||
Une fois les principes rédactionnels à adopter définis, automatisez au maximum. Vous pouvez utiliser des [contrôles CI](/fr/deploy/ci) ou des analyseurs comme [Vale](https://vale.sh).
|
||
|
||
<Tip>
|
||
Utilisez un [workflow](/fr/agent/workflows) 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.
|
||
</Tip>
|
||
|
||
<div id="related-pages">
|
||
## Pages connexes
|
||
</div>
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="Types de contenu" icon="folder-tree" href="/fr/guides/content-types">
|
||
Choisissez le type de contenu adapté à 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="Mettre le texte en forme" 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 visibilité de votre documentation.
|
||
</Card>
|
||
</CardGroup> |