> 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/creating-content/styleguide.md). # Guide de style Un guide de style contient les règles et conventions d’écriture de votre équipe. C’est la source unique de vérité pour 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 les relecteurs disposent d’une référence commune sur la manière d’écrire, de sorte que la documentation reste cohérente, quel que soit le nombre d’éditeurs. * **GitBook Agent :** l’Agent lit votre guide de style et le considère comme la source de vérité qu’il doit suivre chaque fois qu’il rédige, modifie ou relit du contenu. Il remplace les valeurs par défaut et les conventions générales d’écriture propres à l’Agent. {% hint style="info" %} **Les guides de style sont en accès anticipé.** La fonctionnalité de guide de style est déployée progressivement. Si vous ne la voyez pas encore, elle n’est pas activée pour votre organisation. {% endhint %} ### 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, afin que cette page guide toujours son travail. Il lit les autres pages uniquement à la demande, en s’appuyant sur la table des matières. **Placez 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 pourra récupérer si besoin. Vos modifications priment 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 sert de contexte aux lecteurs humains, pas d’instruction pour l’Agent. Si une convention vous importe, é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é : * **Les règles numérotées** (comme `G-10` ou `MS-9`) constituent le niveau applicable. L’Agent signale directement les violations de ces règles et cite l’identifiant, afin que vous puissiez relier chaque alerte à la règle exacte qui l’a générée. * **Les recommandations non numérotées** — comme une description de ton — relèvent du jugement. L’Agent les applique lors de l’écriture et les propose comme suggestions à la 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, où que se trouve la règle. Ne renumérotez jamais et ne réutilisez jamais un identifiant — les alertes passées et votre journal des décisions s’y réfèrent. 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émarrage, le `SG-` préfixe est à modifier — mais conservez-le stable une fois que vous commencez à utiliser le guide. {% endhint %} ### Créer un guide de style Vous pouvez lancer 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 configurez-le à partir de là. Choisissez ensuite un point de départ (détaillé ci-dessous) : * Réutilisez un guide de style existant de votre organisation. * Choisissez un modèle — Starter, Google ou Microsoft. * Importez un fichier ou importez 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 n’importe quel 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, avec les sites qui les utilisent. Lorsque vous en choisissez un, vous pouvez : * **L’utiliser tel quel** — l’attacher en le partageant 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 pourrez faire évoluer indépendamment. #### Choisir un modèle GitBook propose trois modèles de départ :
ModèleIdéal pour
Modèle de démarrageDéfinir votre propre voix et vos propres règles à partir de zéro. Chaque section explique ce qui doit y figurer et pourquoi, avec une structure à compléter vous-même.
Guide de style GoogleUne rédaction 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 rédaction chaleureuse, simple et humaine pour un large public — y compris les 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 issues 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 modifiable : un modèle est un point de départ, pas un contrat. {% hint style="info" %} GitBook examine et met à jour les modèles de base lorsque les guides sources changent, afin que les modèles restent synchronisés avec les guides dont ils sont générés. {% endhint %} **Personnaliser les sections « Besoin de votre contribution »** Chaque modèle signale les parties que vous devez personnaliser avec l’indication **Besoin de votre contribution** . Avant que votre guide de style soit prêt à l’emploi, parcourez-les — 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 vos fonctionnalités et tous les termes sur lesquels votre équipe débat, ajoutés à la liste de mots * Un responsable, une fréquence de relecture 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’indication est prérempli et prêt à être utilisé tel quel. Les règles provisoires que vous n’avez pas encore remplies 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 choisir. 3. Si vous le souhaitez, activez **Améliorer l’importation avec l’IA** pour affiner et nettoyer automatiquement le contenu importé. 4. Cliquez sur **Démarrer 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. Si vous le souhaitez, 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. ### Que mettre dans votre guide de style Un guide de style est particulièrement utile lorsqu’il consigne les décisions les plus faciles à rater ou à rendre incohérentes au sein d’une équipe. Les modèles partagent une structure commune, et chaque section tranche un type différent de débat de style : * **Introduction :** à quoi sert le guide et à quoi sert votre documentation. Un guide qui a un objectif explicite est maintenu ; sans cela, il est abandonné. * **Public et portée :** qui lit votre documentation, qui l’écrit, et ce que couvre le guide. La moitié des débats de style sont en réalité des débats de public déguisés ; réglez-les ici une bonne fois pour toutes. * **Voix et ton :** la manière dont vous vous adressez au lecteur et le niveau de formalité ou de convivialité, ainsi que les règles applicables à tout ce qui peut être vérifié mécaniquement, comme la ponctuation et les contractions. * **Liste de mots :** les noms de vos produits, l’utilisation exacte des majuscules/minuscules, les termes préférés et les débats terminologiques tranchés. Enregistrez uniquement 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 compte autant que la règle : elle empêche l’Agent de signaler du texte légitime. * **Mise en forme :** la casse des titres, les éléments d’interface, les liens, le code, et quand utiliser des listes, des étapes, des conseils et d’autres blocs. * **Procédures d’écriture :** 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 les plus stressés. Facultatif ; supprimez cette section si votre documentation ne contient pas de texte d’erreur. * **Écriture accessible** et **Langage inclusif :** règles presque universelles et vérifiables que la plupart des équipes adoptent telles quelles. * **Types de contenu et modèles :** vos 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, la fréquence de relecture et la manière de proposer une modification. 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 explique pourquoi, afin que les débats tranchés restent tranchés. 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 modification, puis fusionnez-les lorsque 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 guide — l’agent d’édition applique les mêmes règles d’écriture partout, et toute votre documentation suit une seule voix. Après avoir créé un guide de style, GitBook propose de le lier à tout autre site de votre organisation qui n’en possède pas encore. Vous pouvez aussi associer un guide de style existant — partagé ou dupliqué — lors de la configuration d’un site, comme décrit précédemment. 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 **Détacher**. Le détachement conserve le guide de style — il peut toujours être utilisé par d’autres sites. Si aucun autre site n’y fait référence, GitBook propose de le supprimer définitivement. ### Mettez votre guide de style au travail Une fois votre guide de style en place, demandez à GitBook Agent de parcourir votre documentation existante pour l’aligner sur le guide de style. Ensuite, 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 à la 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 de guide de style sur une demande de modification Lorsque votre site dispose d’un guide de style, GitBook Agent apparaît comme relecteur suggéré sur vos demandes de modification, avec l’étiquette **Revue du guide de style**: 1. Dans votre demande de modification, 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 **Demander** à côté de **GitBook Agent** pour qu’il lance une revue du guide de style de la demande de modification. Vous pouvez y ajouter des relecteurs humains, 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 modification s’il trouve des violations, en citant les règles qui ont généré chaque alerte. ### 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 — et non 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é par rapport au 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 issue d’un guide amont, d’une connaissance générale du bon style ou de tout autre guide de style qu’il connaît, à moins que la règle ne soit écrite dans votre guide de style. L’Agent respecte aussi quelques points sur la manière dont vos règles sont rédigées : * **Les règles provisoires sont inactives.** Les pages de modèle contiennent du texte provisoire entre crochets comme `[Nom du produit]` ou `[Ajouter une règle]`. Une règle dont le contenu est encore du texte provisoire n’est pas encore une règle — l’Agent ne l’appliquera pas. Si votre guide de style est principalement composé 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, plutôt que de présenter un état partiel comme complet. * **Les exceptions sont respectées.** De nombreuses règles comportent des exceptions (« le passif est acceptable lorsque l’agent est inconnu »). Le 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 ressemble à une instruction claire et vérifiable (« n’utilisez jamais de point-virgule »), l’Agent l’applique et la cite par une courte citation au lieu d’un identifiant. #### Quand l’Agent relit Lors d’une revue de guide de style — sur une page ou sur une demande de modification — l’Agent signale les problèmes mais ne change rien. Chaque alerte comprend : * **Règle :** l’identifiant de règle de 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ù le problème se produit, ainsi que le texte en cause. * **Problème :** une phrase indiquant la violation. * **Correction :** le texte corrigé, prêt à être collé. Les revues sont limitées à **5 alertes par passage**. S’il existe davantage de problèmes, l’Agent signale les 5 plus prioritaires et termine par une note d’une ligne indiquant qu’il existe d’autres problèmes, avec un décompte. Les alertes sont classées 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 des pages. Les recommandations non numérotées — voix, ton et conseils structurels — n’apparaissent jamais comme des alertes. Au maximum, l’Agent ajoute une seule note combinée « à faire vérifier par un humain » par passage, couvrant tout ce qui relève du niveau du jugement. #### Quand l’Agent modifie Lorsque vous demandez à l’Agent de corriger un contenu ou de l’aligner sur votre guide de style, il applique directement les règles numérotées partout où la correction est sans ambiguïté. Lorsqu’une règle admet deux résultats défendables, l’Agent laisse le texte inchangé et le liste comme suggestion au lieu de deviner. Après la modification, l’Agent fournit un résumé des changements regroupé par identifiant de règle, avec des compteurs — par exemple : « G-7 : remplacé “click on” par “click”, 6 occurrences. » Les suggestions du niveau du jugement apparaissent dans une liste courte 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 des blocs de code, du code inline, des sorties de commandes ou des identifiants d’API et de produit * Les citations directes et les contenus 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 rédigées, même lorsqu’il pourrait « ne pas être d’accord » — il n’adoucit, ne renforce ni ne réinterprète jamais une règle pour l’adapter au contenu. Si une règle est ambiguë dans sa formulation, l’Agent en applique la lecture littérale et signale l’ambiguïté dans sa note destinée à la 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 un 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 des consignes courtes, propres au site ; un guide de style est un document complet et partagé de vos règles d’écriture. --- # 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/creating-content/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.