> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/creer-du-contenu/styleguide.md). # Guide de style Un guide de style rassemble les règles et conventions rédactionnelles de votre équipe. C'est la source unique de vérité sur la manière dont le contenu de votre site doit être rédigé — voix et ton, terminologie, mise en forme et structure. Un guide de style s'adresse à deux publics : * **Votre équipe :** les rédacteurs et relecteurs disposent d'une référence commune sur la manière d'écrire, afin que la documentation reste cohérente, quel que soit l'éditeur. * **GitBook Agent :** l'Agent lit votre guide de style et le traite comme la source de vérité qu'il doit suivre chaque fois qu'il rédige, modifie ou relit du contenu. Il remplace les réglages par défaut et les conventions rédactionnelles générales de l'Agent. ### Comment GitBook Agent utilise votre guide de style GitBook Agent charge intégralement la première page de votre guide de style dans son contexte à chaque tâche, de sorte que cette page oriente toujours son travail. Il ne lit les autres pages qu'à la demande, en s'appuyant sur la table des matières. **Mettez vos règles principales sur la première page.** Conservez-y toutes les règles que vous souhaitez faire appliquer, et utilisez les pages supplémentaires pour les détails que l'Agent peut charger en contexte lorsque c'est pertinent. Vos modifications l'emportent toujours : modifiez une règle et l'Agent suit votre version ; supprimez une règle et l'Agent cesse de l'appliquer. Le guide de style est la seule source de règles de l'Agent. Si votre guide de style mentionne un guide amont — comme celui de Google ou de Microsoft — comme base, cette mention relève du contexte pour les lecteurs humains, pas d'une instruction à l'Agent. Si une convention compte pour vous, écrivez-la. #### Règles applicables et recommandations Les guides de style distinguent deux niveaux de contenu, et la différence tient au fait qu'une règle comporte ou non un identifiant numéroté : * **Règles numérotées** (comme `G-10` ou `MS-9`) constituent le niveau applicable. L'Agent signale directement leurs violations et cite l'identifiant, afin que vous puissiez relier chaque signalement à la règle exacte qui l'a généré. * **Recommandations non numérotées** — comme une description du ton — relèvent du jugement. L'Agent les applique lors de la rédaction et les propose comme suggestions pour une relecture humaine, mais ne les signale jamais comme des violations. Pour ajouter une règle applicable, attribuez-lui le numéro suivant après le plus élevé existant, quel que soit l'endroit où se trouve la règle. Ne renumérotez jamais et ne réutilisez jamais un identifiant — les signalements passés et votre journal de décisions y font référence. Avec le temps, les numéros ne correspondront plus à l'ordre des pages ; c'est normal. Le seul rôle d'un identifiant est de rester stable. {% hint style="info" %} Dans le modèle de départ, le `SG-` préfixe est à vous de le modifier — mais conservez-le stable une fois que vous commencez à utiliser le guide. {% endhint %} ### Créer un guide de style Vous pouvez commencer la configuration du guide de style à partir de deux endroits : * Dans la barre latérale de votre site, sous **Outils**, cliquez sur **Guide de style**, puis cliquez sur **Configurer**. * Ouvrez **Paramètres → Guide de style** et le configurer depuis là. Choisissez ensuite un point de départ (détaillé ci-dessous) : * Réutiliser un guide de style existant de votre organisation. * Choisir un modèle — Starter, Google ou Microsoft. * Importer un fichier ou depuis une URL, si vous avez déjà un guide de style. La première fois que vous ouvrez votre guide de style, GitBook affiche une courte introduction expliquant que vous le modifiez comme tout autre contenu. #### Utiliser un guide de style existant Si votre organisation utilise déjà des guides de style ailleurs, ils apparaissent en haut de l'écran de configuration, ainsi que les sites qui les utilisent. Quand vous en choisissez un, vous pouvez : * **L'utiliser tel quel** — le partager avec les autres sites qui l'utilisent. Les modifications s'appliquent partout où il est utilisé. * **Le dupliquer** — créer une copie dédiée à ce site (nommée `Guide de style - {site name}`) que vous pouvez faire évoluer indépendamment. #### Choisir un modèle GitBook propose trois modèles de départ :
ModèleIdéal pour
Modèle de départDéfinir votre propre voix et vos propres règles à partir de zéro. Chaque section explique ce qui doit s'y trouver et pourquoi, avec une structure de base que vous complétez vous-même.
Guide de style GoogleUne écriture claire, précise et professionnelle pour un public de développeurs. Généré à partir du guide de style de la documentation développeur de Google.
Guide de style MicrosoftUne écriture chaleureuse, simple et humaine pour un large public — y compris des lecteurs qui ne sont pas experts en technologie. Généré à partir du Microsoft Writing Style Guide.
Les modèles Google et Microsoft sont préremplis avec des règles applicables provenant de leurs guides sources — couvrant la voix, les listes de mots, la grammaire, la mise en forme, les procédures, l'écriture accessible et le langage inclusif — et sont prêts à être utilisés tels quels. Tout est à vous de modifier : un modèle est un point de départ, pas un contrat. {% hint style="info" %} GitBook révise et met à jour les modèles de base lorsque les guides sources changent, afin que les modèles restent à jour avec les guides dont ils sont générés. {% endhint %} **Personnalisez les sections « Besoin de vos informations »** Chaque modèle marque avec un indicateur **Besoin de vos informations** les parties que vous devez personnaliser. Avant que votre guide de style soit prêt à l'emploi, passez-les en revue — elles incluent généralement : * La date d'instantané de la version du guide de base reflétée par le modèle (modèles Google et Microsoft) * Le nom de votre produit et la mission de votre documentation * Qui lit et rédige votre documentation, et ce que couvre le guide * Les noms de vos produits, les noms de fonctionnalités et tous les termes sur lesquels votre équipe débat, ajoutés à la liste de mots * Un responsable, un rythme de révision et la manière de proposer des changements * Une première entrée dans le journal des décisions Tout ce qui n'a pas d'indicateur est prérempli et prêt à être utilisé tel quel. Les règles modèle que vous n'avez pas encore renseignées sont inactives — l'Agent ne les appliquera pas tant que vous n'aurez pas remplacé les espaces réservés par du contenu réel. #### Importer un fichier Si vous conservez déjà un guide de style dans un autre outil, vous pouvez l'importer au lieu de partir d'un modèle : 1. Dans l'écran de configuration, cliquez sur **Importer un fichier**. 2. Déposez vos fichiers Markdown, HTML, DOCX ou ZIP — ou parcourez vos fichiers pour les sélectionner. 3. Au besoin, activez **Améliorer l'importation avec l'IA** pour affiner et nettoyer automatiquement le contenu importé. 4. Cliquez sur **Lancer l'importation**. #### Importer depuis une URL Si votre guide de style est publié en ligne, GitBook peut l'importer directement : 1. Dans l'écran de configuration, cliquez sur **Importer depuis une URL**. 2. Saisissez le lien de la documentation que vous souhaitez importer. 3. Au besoin, activez **Améliorer l'importation avec l'IA** pour affiner et nettoyer automatiquement le contenu importé. GitBook importe toutes les pages publiques sous l'URL que vous saisissez, jusqu'à 200 pages. Par exemple, si vous importez `website.com/docs/`, cela inclura `website.com/docs/article`, mais pas `website.com/other-parent/page`. Pour les sites plus volumineux, importez séparément des sous-chemins plus petits. ### Ce qu'il faut mettre dans votre guide de style Un guide de style est particulièrement utile lorsqu'il consigne les décisions faciles à rater ou incohérentes d'une équipe à l'autre. Les modèles partagent une structure commune, et chaque section tranche une catégorie différente de débat stylistique : * **Introduction :** à quoi sert le guide et à quoi sert votre documentation. Un guide qui a une finalité déclarée est maintenu ; un guide sans finalité est abandonné. * **Public et périmètre :** qui lit votre documentation, qui l'écrit et ce que couvre le guide. La moitié des débats stylistiques sont en réalité des débats sur le public ; tranchez-les ici, une fois pour toutes. * **Voix et ton :** la manière dont vous vous adressez au lecteur et votre degré de formalité ou de convivialité, ainsi que des règles applicables pour tout ce qui peut être vérifié mécaniquement, comme la ponctuation et les contractions. * **Liste de mots :** les noms de vos produits, l'orthographe exacte, les termes privilégiés et les débats terminologiques tranchés. Ne consignez que les termes sur lesquels votre équipe a débattu ; gardez des entrées concises. * **Grammaire et mécanique :** les valeurs par défaut au niveau de la phrase pour la personne, le temps et la voix. La colonne des exceptions est aussi importante que la règle : elle évite que l'Agent signale des textes légitimes. * **Mise en forme :** casse des titres, éléments d'interface, liens, code, et quand utiliser des listes, des étapes, des indications et d'autres blocs. * **Procédures de rédaction :** format des étapes, verbes à l'impératif, une action par étape. * **Messages d'erreur et états d'échec :** règles de ton pour les moments où les lecteurs sont le plus stressés. Optionnel ; supprimez cette section si votre documentation ne contient pas de texte d'erreur. * **Écriture accessible** et **Langage inclusif :** règles vérifiables, presque universelles, que la plupart des équipes adoptent telles quelles. * **Types de contenu et modèles :** les types de pages, afin que les rédacteurs et l'Agent sachent quelle structure une page doit suivre. De nombreuses équipes utilisent un cadre comme [Diátaxis](https://diataxis.fr/). * **Responsabilité et mises à jour :** le responsable, le rythme de révision et la manière de proposer un changement. Un guide dont personne n'est responsable dérive vers la fiction. * **Journal des décisions :** la mémoire institutionnelle de votre organisation. Modifier une règle modifie ce que l'Agent applique ; le journal rappelle pourquoi, afin que les débats tranchés le restent. Enregistrez ici chaque écart volontaire par rapport à un guide de base. ### Modifier votre guide de style Vous modifiez un guide de style de la même manière que le reste de votre documentation : * **Dans GitBook :** effectuez vos modifications dans une demande de changement, puis fusionnez-les quand vous êtes prêt. * **Avec Git Sync :** si le guide de style est synchronisé avec GitHub ou GitLab, modifiez-le en Markdown dans votre dépôt. Pour ouvrir votre guide de style, utilisez l'entrée **Guide de style** dans la barre latérale de votre site, ou l'action **Modifier** dans **Paramètres → Guide de style**. ### Partager un guide de style entre plusieurs sites Un guide de style appartient à votre organisation, donc plusieurs sites peuvent s'appuyer sur le même — l'agent de modification applique les mêmes règles rédactionnelles partout, et toute votre documentation suit une voix unique. Après avoir créé un guide de style, GitBook propose de le relier à tous les autres sites de votre organisation qui n'en ont pas encore. Vous pouvez aussi rattacher un guide de style existant — partagé ou dupliqué — lors de la configuration d'un site, comme décrit plus haut. Pour voir tous les guides de style de votre organisation et les sites qui utilisent chacun d'eux, ouvrez l'entrée **Guides de style** dans la barre latérale de votre organisation. #### Détacher un guide de style Pour empêcher un site d'utiliser son guide de style, ouvrez **Paramètres → Guide de style** et cliquez sur **Dissocier**. Le détachement conserve le guide de style — il peut encore être utilisé par d'autres sites. Si aucun autre site n'y fait référence, GitBook propose de le supprimer définitivement. ### Mettre votre guide de style au travail Une fois votre guide de style en place, demandez à GitBook Agent d'effectuer une passe sur votre documentation existante afin de l'aligner sur le guide de style. À partir de là, l'Agent vérifie que votre guide de style est respecté chaque fois qu'il rédige, modifie ou relit du contenu — en signalant les violations des règles numérotées avec leurs identifiants, et en proposant les recommandations non numérotées comme suggestions pour relecture humaine. Il existe deux façons principales de lancer une revue de guide de style sur vos modifications : #### Relire une page avant de demander une revue Pendant que vous travaillez sur une page, vous pouvez demander à l'Agent de la vérifier par rapport à votre guide de style — utilisez **Vérifier la cohérence avec le guide de style** dans le menu Améliorer, ou demandez-le dans le chat. L'Agent examine la page et laisse des commentaires résumant ce qu'il a trouvé. #### Demander une revue du guide de style sur une demande de changement Lorsque votre site dispose d'un guide de style, GitBook Agent apparaît comme relecteur suggéré sur vos demandes de changement, étiqueté **Revue du guide de style**: 1. Dans votre demande de changement, cliquez sur **Demander une revue**. 2. Ajoutez un titre et une description pour vos modifications — ou cliquez sur **Générer** pour laisser l'Agent les rédiger à partir de vos modifications. 3. Sous **Relecteurs**, cliquez sur **Request** à côté de **agent GitBook** pour qu'il effectue une revue du guide de style de la demande de changement. Vous pouvez ajouter des relecteurs humains à côté, ou laisser la liste vide pour notifier tous les relecteurs de votre organisation. L'Agent examine vos modifications au regard du guide de style et demande des changements sur la demande de changement s'il trouve des violations, en citant les règles qui ont généré chaque signalement. ### Comment l'Agent applique votre guide de style Lorsque GitBook Agent travaille avec votre guide de style, sa mission est de faire respecter vos règles — pas d'améliorer l'écriture de manière générale. Il est conçu pour être précis, prudent et cohérent : le même contenu vérifié avec le même guide de style produit toujours les mêmes résultats. #### Votre guide de style est la seule source de règles L'Agent n'applique jamais une règle provenant d'un guide amont, d'une connaissance générale des bonnes pratiques rédactionnelles ou de tout guide de style qu'il connaît, sauf si la règle est écrite dans votre guide de style. L'Agent respecte également quelques points sur la manière dont vos règles sont rédigées : * **Les règles modèle sont inactives.** Les pages de modèle contiennent du texte réservé entre crochets comme `[Nom du produit]` ou `[Ajouter une règle]`. Une règle dont le contenu est encore du texte réservé n'est pas encore une règle — l'Agent ne l'appliquera pas. Si votre guide de style est surtout constitué d'espaces réservés, l'Agent vous indique qu'il est largement incomplet et que l'application est limitée aux règles que vous avez terminées, au lieu de présenter une validation partielle comme exhaustive. * **Les exceptions sont respectées.** De nombreuses règles comportent des exceptions (« le passif convient lorsque l'agent est inconnu »). Un texte qui relève d'une exception listée n'est pas une violation. * **Les règles explicites comptent même sans identifiant.** Si vous rédigez une règle sans identifiant numéroté mais qu'elle se lit comme une instruction explicite et vérifiable (« n'utilisez jamais de point-virgule »), l'Agent l'applique et la cite sous forme de courte citation plutôt que d'identifiant. #### Quand l'Agent examine Lors d'une revue de guide de style — sur une page ou sur une demande de changement — l'Agent signale les problèmes mais ne modifie rien. Chaque signalement comprend : * **Règle :** l'identifiant de la règle dans votre guide de style (par exemple `G-10`), ou une courte citation de votre règle si elle n'a pas d'identifiant. * **Emplacement :** le titre ou la ligne où se trouve le problème, ainsi que le texte fautif. * **Problème :** une phrase indiquant la violation. * **Correction :** le texte corrigé, prêt à être collé. Les revues sont limitées à **5 signalements par passe**. S'il existe davantage de problèmes, l'Agent signale les 5 plus prioritaires et termine par une note sur une seule ligne indiquant qu'il existe d'autres problèmes, avec un décompte. Les signalements sont classés par catégorie — d'abord le choix des mots et la terminologie, puis la mise en forme et la ponctuation, ensuite la grammaire, puis les procédures — et, au sein d'une catégorie, dans l'ordre de la page. Les recommandations non numérotées — voix, ton et conseils structurels — n'apparaissent jamais comme des signalements. Au maximum, l'Agent ajoute une seule note combinée « à faire vérifier par un humain » par passe, couvrant tout ce qui relève du niveau du jugement. #### Quand l'Agent modifie Lorsque vous demandez à l'Agent de corriger du contenu ou de l'aligner sur votre guide de style, il applique directement les règles numérotées partout où la correction ne laisse aucune ambiguïté. Lorsqu'une règle a deux issues défendables, l'Agent laisse le texte inchangé et l'inscrit comme suggestion plutôt que de deviner. Après la modification, l'Agent produit un résumé des changements regroupé par identifiant de règle, avec des décomptes — par exemple, « G-7 : remplacé 'click on' par 'click', 6 occurrences. » Les suggestions relevant du niveau du jugement apparaissent dans une courte liste séparée à la fin. #### Ce que l'Agent ne touche jamais Dans les revues comme dans les modifications, l'Agent ne signale ni ne modifie jamais : * Le contenu dans les blocs de code, le code en ligne, la sortie de commande ou les identifiants d'API et de produit * Les citations directes et les matériaux cités * Le texte exempté par la propre exception d'une règle * Le sens ou les faits de votre contenu * Tout ce qui n'est couvert que par une règle absente de votre guide de style #### Cohérence L'Agent applique les règles telles qu'elles sont écrites, même lorsqu'il pourrait être en « désaccord » — il n'atténue, n'aggrave ni ne réinterprète jamais une règle pour l'adapter au contenu. Si une règle est ambiguë telle qu'elle est écrite, l'Agent applique sa lecture littérale et note l'ambiguïté dans son commentaire pour relecture humaine, plutôt que d'inventer une intention. Et si votre site n'a aucun guide de style configuré, l'Agent ne se rabat pas sur son jugement général — il vous propose plutôt de vous aider à en créer un. ### Guides de style et instructions personnalisées Un guide de style complète les instructions personnalisées au niveau du site que vous pouvez donner à GitBook Agent. Les instructions personnalisées sont de courtes consignes propres au site ; un guide de style est un document complet et partagé de vos règles rédactionnelles. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/fr/creer-du-contenu/styleguide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.