Guide de style

Définissez les règles d’écriture de votre équipe dans un espace dédié au guide de style, et maintenez la cohérence de chaque contributeur, humain ou Agent GitBook.

Un guide de style est un espace dédié qui regroupe les règles et conventions rédactionnelles 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, afin que la documentation reste cohérente, quel que soit le contributeur.
• 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 ses propres valeurs par défaut et les conventions rédactionnelles générales.

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.

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, à l’aide de la table des matières.

Placez vos règles principales sur la première page. Gardez-y toutes les règles que vous souhaitez faire appliquer, et utilisez des pages supplémentaires pour les détails que l’Agent pourra charger si nécessaire. 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 pour les lecteurs humains, et non d’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 porte 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 leurs violations et cite l’identifiant, ce qui vous permet de relier chaque alerte à la règle exacte qui l’a déclenchée.
• Les recommandations non numérotées — comme une description de voix — 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 prochain numéro après le plus élevé existant, à l’endroit où se trouve la règle. Ne renumérotez jamais et ne réutilisez jamais un identifiant — les anciennes alertes 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.

Dans le modèle de démarrage, le SG- préfixe peut être modifié — mais gardez-le stable une fois que vous commencez à utiliser le guide.

Créer un guide de style

Vous pouvez lancer la configuration du guide de style à partir de plusieurs endroits :

• Depuis le tableau de bord de votre site, allez dans Outils, cliquez sur Guide de style, puis cliquez sur Configurer.
• Ouvrez Paramètres du site → Guide de style et configurez-le 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 l’éditez comme n’importe quel autre espace.

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 tel quel aux autres sites qui l’utilisent. Les modifications s’appliquent partout où il est utilisé.
• Le dupliquer — créer une copie dédiée pour 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èle	Idéal pour
Modèle Starter	Dé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 Google	Une rédaction claire, précise et professionnelle pour un public de développeurs. Généré à partir du guide de style de la documentation pour développeurs de Google.
Guide de style Microsoft	Une rédaction 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 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.

GitBook examine et met à jour les modèles de base lorsque les guides sources changent, afin que les modèles restent alignés sur les guides dont ils sont issus.

Personnaliser les sections « Besoin de votre contribution »

Chaque modèle signale les parties que vous devez personnaliser avec un indicateur Besoin de votre contribution . Avant que votre guide de style soit prêt à l’emploi, complétez-les — elles incluent généralement :

• La date de capture 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, une fréquence de relecture et la manière de proposer des modifications
• 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 de substitution que vous n’avez pas encore complété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-les pour les sélectionner.
3. En option, 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 documentation que vous souhaitez importer.
3. En option, 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/, il 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 faciles à mal appliquer ou incohérentes au sein d’une équipe. Les modèles partagent une structure commune, et chaque section tranche une catégorie différente de débat de style :

• Introduction : à quoi sert le guide et à quoi sert votre documentation. Un guide qui a un objectif explicite est entretenu ; sans objectif, il est abandonné.
• Public et périmètre : qui lit votre documentation, qui la rédige et ce que couvre le guide. La moitié des débats de style sont en réalité des débats sur le public déguisés ; réglez-les ici une bonne fois pour toutes.
• Voix et ton : comment vous vous adressez au lecteur et à quel point vous êtes formel ou convivial, 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, les majuscules exactes, les termes préférés et les débats terminologiques tranchés. N’enregistrez que les termes qui ont fait l’objet d’un débat ; soyez concis.
• Grammaire et mécanique : les paramètres 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 un 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 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 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 vérifiables et quasi universelles 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.
• Propriété et mises à jour : le responsable, la fréquence de relecture et la manière de proposer une modification. Un guide que personne ne possède dérive vers la fiction.
• Journal des décisions : la mémoire de votre organisation. Modifier une règle modifie ce que l’Agent applique ; le journal se souvient 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

Un guide de style est un espace ; vous le modifiez donc de la même manière que le reste de votre documentation :

• Dans GitBook : faites vos modifications dans une demande de changement, puis fusionnez-les lorsque vous êtes prêt.
• Avec Git Sync : si l’espace du 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’élément Guide de style dans la barre latérale de votre site, ou l’action Modifier dans Paramètres du site → 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 rédaction 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 a 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.

Dissocier un guide de style

Pour qu’un site n’utilise plus son guide de style, ouvrez Paramètres du site → Guide de style et choisissez Dissocier. La dissociation conserve l’espace du guide de style — il peut encore être utilisé par d’autres sites. Si aucun autre site ne s’y réfère, GitBook propose de le supprimer définitivement.

Mettez votre guide de style au travail

Avec votre guide de style en place, demandez à GitBook Agent de passer en revue votre documentation existante afin de l’aligner sur le guide de style. À partir de ce moment-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 une relecture humaine.

Il existe deux façons principales de lancer une relecture de guide de style sur vos modifications :

Relire une page avant de demander une relecture

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 posez la question dans le chat. L’Agent relit la page et laisse des commentaires résumant ce qu’il a trouvé

Demander une relecture 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, avec l’étiquette Relecture du guide de style:

1. Dans votre demande de changement, cliquez sur Demander une relecture.
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 effectue une relecture du guide de style de la demande de changement. 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 changement s’il trouve des violations, en citant les règles à l’origine de chaque alerte.

Comment l’Agent applique votre guide de style

Lorsque GitBook Agent travaille avec votre guide de style, sa mission est de vérifier la conformité à vos règles — et non d’améliorer la rédaction en général. Il est conçu pour être précis, conservateur 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 provenant d’un guide amont, de connaissances générales sur un bon style, ni d’aucun guide de style qu’il connaît, sauf si cette règle est écrite dans votre guide de style.

L’Agent respecte aussi quelques aspects de la manière dont vos règles sont rédigées :

• Les règles provisoires sont inactives. Les pages modèles contiennent du texte de remplacement entre crochets comme [Nom du produit] ou [Ajouter une règle]. Une règle dont le contenu est encore du texte de remplacement n’est pas encore une règle — l’Agent ne l’appliquera pas. Si votre guide de style est surtout composé de substitutions, l’Agent vous indiquera qu’il est largement incomplet et que l’application des règles se limite à celles que vous avez terminées, au lieu de présenter un aperçu partiel comme s’il était complet.
• Les exceptions sont respectées. De nombreuses règles comportent des exceptions (« le passif est acceptable quand l’acteur 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 claire et vérifiable (« n’utilisez jamais de points-virgules »), l’Agent l’applique et la cite par une courte citation plutôt que par un identifiant.

Quand l’Agent relit

Lors d’une relecture de guide de style — sur une page ou sur une demande de changement — l’Agent signale les problèmes mais ne modifie rien. Chaque alerte inclut :

• 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ù le problème se produit, ainsi que le texte concerné.
• Problème : une phrase indiquant la violation.
• Correction : le texte corrigé, prêt à être collé.

Les relectures sont limitées à 5 alertes par passage. S’il y a 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, à l’intérieur d’une catégorie, dans l’ordre des pages.

Les recommandations non numérotées — voix, ton et conseils structurels — n’apparaissent jamais comme alertes. Au maximum, l’Agent ajoute par passage une seule note combinée « à faire relire par un humain » 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 est sans ambiguïté. Lorsqu’une règle admet deux issues 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 comptes — par exemple, « G-7 : remplacé « click on » par « click », 6 occurrences. » Les suggestions relevant du jugement apparaissent dans une courte liste séparée à la fin.

Ce que l’Agent ne touche jamais

Dans les relectures comme dans les modifications, l’Agent ne signale ni ne change jamais :

• Le contenu des blocs de code, du code en ligne, des sorties de commande 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 qui ne figure pas dans votre guide de style

Cohérence

L’Agent applique les règles telles qu’écrites, même lorsqu’il pourrait ne pas être d’accord — il n’atténue, n’intensifie ni ne réinterprète jamais une règle pour l’adapter au contenu. Si une règle est ambiguë telle qu’elle est rédigée, l’Agent en applique la lecture littérale et signale l’ambiguïté dans sa note destinée à une relecture humaine, plutôt que d’inventer une intention. Et si votre site n’a pas de guide de style configuré, l’Agent ne retombe pas sur un jugement général — il 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 spécifiques au site ; un guide de style est un document complet et partagé de vos règles rédactionnelles.