Documentation
Documentation est la section d'un produit qui regroupe ses manuels, ses guides et ses fiches techniques. Un gestionnaire dresse la liste des documents dont le produit a besoin et précise ce que chacun doit couvrir. Les auteurs les rédigent sous forme de brouillons, les relecteurs vérifient ces brouillons, et un document approuvé peut être publié pour ses lecteurs. Cette page va de la liste des documents jusqu'au moment où un brouillon existe.
Ce que contient Documentation
Chaque produit a une seule liste de documents. Un document se compose de quatre éléments :
- Le document lui-même : un type (par exemple un manuel de maintenance) et un titre.
- Ses sections : une liste numérotée qui indique ce que le document doit couvrir.
- Ses brouillons : les copies de travail de son contenu, nommées Draft v1, Draft v2 et ainsi de suite. Un brouillon se rédige dans l'éditeur et passe en relecture.
- Son document approuvé : ce qui existe une fois qu'un brouillon est approuvé. Il conserve des révisions numérotées et peut être publié.
La rédaction d'un brouillon est décrite dans Brouillons, l'Assistant dans Assistant, et la relecture, l'approbation et la publication dans Relecture et publication.
Ouvrir la documentation d'un produit
Dans Products, sélectionnez le produit, puis Documentation dans la barre latérale. La page Documentation s'ouvre : elle présente les documents du produit sous Required documents (documents requis).
Une personne qui a le rôle Viewer ne voit pas cette page : pour elle, Documentation affiche à la place les documents publiés du produit (voir Lire un document).
Lire la liste des documents
Chaque ligne de la liste affiche le titre du document, une seconde ligne de texte et un état. La seconde ligne indique :
- « 5 of 6 sections ready » (5 sections prêtes sur 6), tant que le brouillon le plus récent est à l'état Draft et que le document compte au moins une section requise (Voir ce qui manque encore précise sur quel brouillon ce décompte est établi) ;
- sinon, la date de création du brouillon le plus récent, par exemple « Created 26 Sep 2026 » ;
- le type du document lorsqu'il n'a aucun brouillon.
| État | Signification |
|---|---|
| Not generated | Le document n'a encore ni brouillon ni document approuvé. |
| Generating… | L'Assistant rédige un brouillon. |
| Importing… | Un fichier PDF ou Word est en cours de conversion en brouillon. |
| Draft | Le brouillon le plus récent est en cours de rédaction. |
| In review | Le brouillon le plus récent a été envoyé en relecture et se trouve chez les relecteurs. |
| Changes requested | Un relecteur a renvoyé le brouillon le plus récent pour qu'il soit retravaillé. |
| Endorsed · awaiting approval | La relecture est terminée et le brouillon le plus récent attend l'approbation. |
| Approved | Le brouillon le plus récent est approuvé et le document n'est pas publié. |
| Rejected | Le brouillon le plus récent a été refusé et le document n'est pas publié. |
| Published · Team | Le document approuvé est publié pour l'audience Team : les membres de votre organisation, une fois connectés. |
| Published · Public | Le document approuvé est publié pour l'audience Public : toute personne qui dispose de son lien. |
Lorsqu'un brouillon plus récent est encore en cours de rédaction ou de relecture, c'est lui qui détermine l'état. Dans l'image, la ligne de l'Operating manual indique Draft, car un brouillon plus récent est en cours de rédaction. Elle ne montre pas que ce document est aussi publié pour l'audience Team : Document details (détails du document) montre, pour un document, à la fois ses brouillons et son état de publication (voir Document details : objet, image de couverture et brouillons). Les états de relecture sont expliqués dans Relecture et publication.
Sur un produit qui n'a encore aucun document, la page affiche « No documents yet » (aucun document pour l'instant) au-dessus du bouton New document (nouveau document).
Qui peut faire quoi
Le rôle d'une personne dans l'organisation détermine ce qu'elle peut faire dans Documentation. Les rôles se définissent sur la page Organisation.
| Rôle | Dans Documentation |
|---|---|
| Manager | Tout : ajouter et supprimer des documents, définir et attribuer les sections, rédiger, relire, approuver et publier. |
| Author | Rédiger : créer et modifier des brouillons, utiliser l'Assistant, commenter, envoyer un brouillon en relecture. |
| Reviewer | Rédiger comme un Author, et en plus relire, valider, approuver et publier. |
| Viewer | Rien dans Documentation. Un Viewer lit les documents publiés. |
| Owner | Tout ce que peut faire un Manager, dans la documentation qu'il a démarrée (voir ci-dessous). |
- La première personne qui ouvre la section Documentation d'un produit gère la documentation de ce produit, même si son rôle est Author ou Reviewer : c'est elle qui l'a démarrée. C'est ainsi que le propriétaire de l'organisation, affiché comme Owner, y obtient ses droits. Un Viewer ne peut pas la démarrer.
- Dans cette page, « un gestionnaire » désigne une personne qui gère la documentation du produit : un Manager, ou la personne qui l'a ouverte la première.
- New document, le bouton Document actions (actions du document), les trois points d'une section, Add section (ajouter une section) et Suggest sections (suggérer des sections) restent visibles, mais grisés, pour les Authors et les Reviewers. Leur infobulle indique « Only managers can change documents and their sections. Ask a manager in your organization. » (seuls les gestionnaires peuvent modifier les documents et leurs sections ; adressez-vous à un gestionnaire de votre organisation).
- Les autres commandes réservées aux gestionnaires ne sont pas proposées aux Authors ni aux Reviewers : Owner (responsable) et Reviewer (relecteur) affichent un nom au lieu d'une liste, l'interrupteur Required (requis) est grisé, et ni Assign across document (attribuer dans tout le document) ni les trois points d'un brouillon sous Outputs (résultats) ne sont affichés.
- Lorsque l'organisation ne compte aucun membre ayant le rôle Reviewer, un Manager voit Approve (approuver) à côté de Submit for review (envoyer en relecture) et peut approuver un brouillon sans cycle de relecture.
Ajouter un document
Dans la boîte de dialogue, Start from (partir de) n'est affiché que si la section Sources du produit contient un fichier PDF ou Word.
Ajouter un document
Un gestionnaire ajoute chaque document dont le produit a besoin, puis précise ce qu'il doit couvrir.
- Dans Documentation, sélectionnez New document.
- Sous Type, choisissez le type de document.
- Si Start from est affiché, conservez An empty document (un document vide).
- Vérifiez le Title (titre) : le choix d'un type le remplit lorsqu'il est vide.
- Sélectionnez Create (créer).
Pour un banc de démonstration livré avec un manuel et un plan d'entretien, ajoutez un Operation Manual (manuel d'exploitation) et un Maintenance Manual (manuel de maintenance).
Le message « Document created » s'affiche et le nouveau document s'ouvre avec la mention « No sections yet ».
Les types sont :
- Maintenance Manual, User Manual (manuel d'utilisation), Operation Manual, Installation Manual (manuel d'installation), Troubleshooting Guide (guide de dépannage) et Training Package (kit de formation) ;
- pour les logiciels : Repository Overview (présentation du dépôt), Architecture et API Reference (référence de l'API).
Le type détermine le modèle standard de sections dont le document peut partir. Le type et le titre d'un document ne peuvent plus être modifiés par la suite.
Transformer un fichier PDF ou Word en brouillon
Un manuel qui existe déjà sous forme de fichier PDF ou Word (.docx) dans la section Sources du produit peut devenir le premier brouillon d'un document. Si le fichier ne se trouve pas encore dans Sources, ajoutez-le d'abord (voir Produits).
Importer un fichier comme brouillon
Un gestionnaire convertit un fichier PDF ou Word du produit en un brouillon modifiable.
- Dans Documentation, sélectionnez New document.
- Sous Start from, choisissez le fichier sous Import one of this product's files (importer l'un des fichiers de ce produit). La boîte de dialogue s'intitule alors Import document.
- Sous Type, choisissez le type de document.
- Vérifiez le Title. S'il était vide, il est rempli avec le nom du fichier.
- Sélectionnez Import.
Le message « Importing document » s'affiche et le nouveau brouillon s'ouvre. Il se remplit à mesure que le fichier est converti ; pendant ce temps, le document affiche Importing… dans la liste.
New document est la même boîte de dialogue, avec An empty document sous Start from et le bouton Create.
Pour un gestionnaire, la même boîte de dialogue s'ouvre aussi depuis Sources : sélectionnez les trois points au bout de la ligne du fichier (le bouton nommé Actions for suivi du nom du fichier), puis Use as draft (utiliser comme brouillon).
Si l'import ne peut pas démarrer, le message « Could not import document » (impossible d'importer le document) s'affiche et aucun document n'est ajouté. Si la conversion échoue ensuite, le brouillon affiche « Could not import the reference file » (impossible d'importer le fichier de référence), accompagné de la raison.
Ouvrir un document
Sélectionnez une ligne de la liste. Le document s'ouvre avec son état, ses sections et les boutons qui servent à créer et à ouvrir ses brouillons.
De gauche à droite, les boutons sont New draft (nouveau brouillon), Submit for review, Open draft (ouvrir le brouillon) avec la flèche Choose a draft (choisir un brouillon), et le bouton Document actions (trois points). New draft est présent dès que le document a une section ou un brouillon ; Submit for review, tant que le brouillon le plus récent est à l'état Draft ou Changes requested ; Open draft, dès que le document a un brouillon ; la flèche, dès qu'il en a plusieurs.
Le menu Document actions, ouvert dans l'image, contient Suggest sections, Use template (utiliser le modèle) et Delete document (supprimer le document). Chacune de ces commandes est décrite plus bas.
Préciser ce qu'un document doit couvrir
Un nouveau document n'a aucune section et affiche « No sections yet ». Un gestionnaire définit les sections de trois façons, qu'il peut combiner. Sur le document vide, ces trois façons sont les liens use the standard template (utiliser le modèle standard) et add them yourself (les ajouter vous-même), et le bouton Suggest sections.
Partir du modèle standard
Ajouter les sections standard
Chaque type de document dispose d'une liste standard de chapitres et de sections qui sert de point de départ.
- Ouvrez le document.
- Sur un document sans section, sélectionnez use the standard template.
- Lisez la liste des chapitres et des sections dans la boîte de dialogue.
- Sélectionnez Add sections (ajouter les sections), ou Discard (abandonner) pour laisser le document tel quel.
Le message « Sections added » s'affiche et les sections apparaissent sous Sections. Vous pouvez ensuite modifier ou supprimer chacune d'elles.
Sur un document qui a déjà des sections, le modèle se trouve dans le menu Document actions : Use template. La boîte de dialogue propose alors Add to existing, qui ajoute les sections du modèle à celles du document, et Replace existing, qui les remplace.
Ajouter une section à la main
Ajouter une section
Un gestionnaire ajoute une section, ou un chapitre qui regroupe des sections.
- Ouvrez le document.
- Sélectionnez Add section sous la liste, ou add them yourself sur un document sans section.
- Saisissez un Title. Une section laissée sans titre prend le nom de son type de contenu.
- Sous Content type (type de contenu), choisissez le genre de contenu que la section accueille.
- Laissez Required activé, sauf si la section est facultative et ne doit pas compter dans la barre au-dessus de la liste.
- Pour créer un chapitre plutôt qu'une section, activez Chapter with sub-sections (chapitre avec sous-sections).
- Sélectionnez Add (ajouter).
Le formulaire se ferme et la nouvelle section apparaît à la fin de la liste. Pour préciser ce qu'elle doit couvrir, ouvrez-la et sélectionnez Edit section (modifier la section) : voir la section « Modifier, déplacer ou supprimer une section », plus bas dans cette page.
| Type de contenu | À choisir pour |
|---|---|
| Procedure (step-by-step) | Une tâche réalisée étape par étape par la personne qui entretient le produit : dépose, installation, réparation, entretien. |
| Description | Le fonctionnement du produit et ses caractéristiques : présentation générale, données techniques, sécurité, introduction. |
| Fault isolation | La recherche et la réparation d'une panne : dépannage, codes de défaut. |
| Parts list | Les pièces : pièces de rechange, outils et consommables. |
| Crew / operating | Une tâche de la personne qui utilise le produit : instructions d'utilisation, commandes. |
| Process | Un calendrier ou un plan : intervalles de maintenance, mise hors service. |
Dans ce formulaire, Advanced (avancé) affiche deux réglages supplémentaires, Weight (poids) et Criticality (criticité) ; le formulaire de modification d'une section en ajoute un troisième, Section number (numéro de section). Tous trois sont décrits dans Modifier, déplacer ou supprimer une section.
Laisser l'Assistant proposer les sections
Suggest sections, présent sur un document sans section et dans le menu Document actions, ouvre l'Assistant avec une demande toute prête : proposer les sections de ce document. Voir Assistant.
Chapitres et sous-sections
Un chapitre est un titre qui regroupe des sections. Il n'a pas de contenu propre : son état compte les sections qu'il regroupe, par exemple « 0 of 2 ready ». Les sections d'un chapitre sont numérotées 1.1, 1.2 et ainsi de suite.
Sélectionnez un chapitre pour l'ouvrir. Ses sections apparaissent d'abord, puis la ligne Chapter settings (réglages du chapitre), qui regroupe l'Owner, le Reviewer, l'interrupteur Required et les trois points du chapitre. Pour ajouter une section sous un chapitre, ou sous une autre section, sélectionnez ses trois points, puis Add sub-item (ajouter un sous-élément).
Modifier, déplacer ou supprimer une section
Sélectionnez une section pour l'ouvrir. Une section ouverte affiche What it must cover (ce qu'elle doit couvrir), son Owner, son Reviewer, l'interrupteur Required et une note sur ce que le document contient déjà pour elle. Si vous désactivez Required, la section reste dans la liste sans être comptée dans « 5 of 6 sections ready ».
Les trois points en bas à droite d'une section ouverte correspondent au bouton nommé Actions for suivi du titre de la section. Un gestionnaire y trouve le reste : Edit section, Add sub-item, Move up (monter), Move down (descendre) et Remove section (retirer la section).
Modifier une section
Un gestionnaire modifie le titre d'une section, ce qu'elle doit couvrir et son type de contenu.
- Ouvrez la section.
- Sélectionnez les trois points en bas à droite de la section, puis Edit section.
- Modifiez le titre, le texte sous What it must cover et le Content type.
- Sélectionnez Save.
La section affiche le nouveau titre et le nouveau texte. Dans ce formulaire, un changement d'Owner ou de Reviewer est enregistré immédiatement, sans Save.
Sous Advanced, le Weight (de 1 à 5) indique combien la section pèse dans le pourcentage de Section coverage (couverture des sections, voir plus bas). Section number et Criticality sont conservés avec la section. La liste ne les affiche pas : elle numérote les sections d'après leur ordre.
Les autres entrées du menu :
- Move up et Move down changent l'ordre. Move up est grisé sur la première section, Move down sur la dernière, et les deux le sont tant que Gaps only (lacunes uniquement) est activé.
Une section peut aussi être glissée par sa ligne jusqu'à sa nouvelle place. Elle se déplace parmi les sections de son propre chapitre, ou parmi les entrées de premier niveau pour un chapitre ou une section hors de tout chapitre ; elle ne peut pas être déposée dans un autre chapitre. Le glissement est désactivé tant que Gaps only est activé.
- Remove section demande une confirmation (« This cannot be undone. » : cette action est irréversible) et, après Remove, supprime la section. Supprimer un chapitre ou une section qui a des sous-éléments les supprime aussi.
Attribuer un responsable et un relecteur
Un gestionnaire attribue à chaque section un Owner, responsable de sa rédaction, et un Reviewer, qui la vérifie. L'attribution ne verrouille pas la section : les autres Authors, Reviewers et gestionnaires peuvent toujours y écrire.
Ouvrez la section et choisissez une personne sous Owner et sous Reviewer. Le choix est enregistré immédiatement et la personne en est informée. Choisissez Unassigned (non attribué) pour retirer l'attribution.
- Owner propose les Managers, les Authors et les Reviewers de l'organisation, ainsi que la personne qui a démarré la documentation du produit ; Reviewer propose les Reviewers, les Managers et cette même personne.
- Sur un chapitre, sous Chapter settings, le choix s'applique à toutes les sections du chapitre. Le champ indique « Multiple people » (plusieurs personnes) lorsque ses sections ont des responsables différents.
- Assign across document, sous la liste, ouvre une liste Owner et une liste Reviewer pour l'ensemble du document. Y choisir une personne lui attribue toutes les sections du document, y compris celles qui étaient attribuées à quelqu'un d'autre. Unassigned retire toutes les attributions.
Les sections dont une personne est responsable ou relectrice figurent sur sa page Vos tâches.
Voir ce qui manque encore
Chaque section porte un état. Cet état est mesuré sur un seul brouillon : le dernier brouillon approuvé du document s'il en a un, sinon son brouillon le plus récent. Ainsi, pendant qu'un nouveau brouillon d'un document approuvé est en cours de rédaction, les états décrivent toujours le brouillon approuvé.
| État d'une section | Signification |
|---|---|
| Ready | Ce brouillon contient une section correspondante, avec du contenu : du texte, un tableau ou une image. |
| Partial | Ce brouillon contient une section correspondante, mais elle est encore vide. |
| Missing | Ce brouillon ne contient aucune section correspondante. |
- La barre au-dessus de la liste compte les sections requises qui sont prêtes : « 5 of 6 sections ready ».
- Gaps only n'affiche que les sections qui ne sont pas prêtes. S'il n'y en a aucune, la liste indique « All sections are ready. There are no gaps to show. » (toutes les sections sont prêtes, il n'y a aucune lacune à afficher).
- Sélectionnez la barre pour ouvrir Section coverage. Vous y trouvez un pourcentage, dans lequel une section Partial compte pour moitié et chaque section compte selon son Weight, puis, sous Needs work (à compléter), chaque section qui n'est pas prête, avec son degré d'avancement et une note.
Ces trois mêmes états parviennent au responsable d'une section, sous forme d'indication, sur la page Vos tâches. L'Outline d'un brouillon a ses propres notes, Not written yet (pas encore rédigée) et Incomplete (incomplète) : ce sont des notes que l'Assistant a laissées sur ce brouillon précis, et non les états décrits ici. Une section peut donc être Ready dans cette liste et Incomplete dans cet Outline. Voir Relecture et publication.
Créer ou ouvrir un brouillon
Les gestionnaires, les Authors et les Reviewers peuvent créer un brouillon dès que le document a une section ou un brouillon.
Créer un brouillon
Un brouillon démarre vide à partir des sections, comme copie d'un autre brouillon, ou rédigé par l'Assistant.
- Ouvrez le document et sélectionnez New draft.
- Sous Start from, conservez Sections, ou choisissez un brouillon sous Copy a draft (copier un brouillon).
- Sélectionnez Create, ou Generate (générer) pour que l'Assistant rédige le brouillon.
Avec Create, le brouillon s'ouvre : à partir de Sections, avec toutes les sections du document disposées, vides ; à partir d'un brouillon, comme copie de ce brouillon.
Generate transmet à l'Assistant ce que vous saisissez sous Instructions for Generate (optional). Le brouillon s'ouvre dès qu'il existe et se remplit à mesure que l'Assistant écrit ; le document affiche Generating… dans la liste. Si le brouillon ne peut pas être rédigé, le message « Could not generate draft » (impossible de générer le brouillon) s'affiche. Voir Assistant.
Ouvrir un brouillon
Open draft ouvre le brouillon le plus récent. La flèche Choose a draft, juste à côté, présente tous les brouillons, du plus récent au plus ancien, avec leur état et leur date de création. Draft v1 est le plus ancien ; le plus récent porte la mention « Latest ». Le travail dans un brouillon est décrit dans Brouillons et dans Tableaux, images et vues 3D.
Document details : objet, image de couverture et brouillons
Sous la liste des sections, sélectionnez le lien Document details.
- Purpose and scope (objet et périmètre) : l'objectif du document. Il est imprimé sur la page de couverture du PDF du document, dont la mise en page est définie par un modèle d'export (voir Modèles d'export).
- L'image de couverture : par défaut, c'est l'image du produit lorsque celui-ci a un modèle 3D, sinon l'image définie dans le modèle d'export. Upload la remplace par une image de votre choix (le bouton indique alors Replace), Remove la retire et Use default rétablit l'image par défaut. La ligne située en dessous indique Custom image, Default image ou No image.
- Outputs : les brouillons du document, du plus récent au plus ancien, chacun avec son état, puis l'Approved document (document approuvé) avec son nombre de révisions. Sélectionnez un brouillon pour l'ouvrir dans l'éditeur. Sélectionnez Approved document pour ouvrir le document approuvé et ses révisions (voir Relecture et publication). Lorsque le document est publié, l'icône au bout de cette ligne l'ouvre tel que les lecteurs le voient.
Les gestionnaires, les Authors et les Reviewers peuvent modifier l'objet et l'image de couverture. Ces deux éléments sont absents de la boîte de dialogue, qui n'affiche alors que Outputs, lorsque l'option Purpose per document (objet par document) est désactivée dans le modèle de document avec lequel vos brouillons sont mis en page (le modèle par défaut de l'organisation, sauf si vous en avez choisi un autre dans l'onglet Preview d'un brouillon) (voir Modèles d'export).
Envoyer le brouillon le plus récent en relecture
Submit for review, en haut du document, envoie le brouillon le plus récent en relecture sans l'ouvrir : le message « Submitted for review » s'affiche et l'état devient In review. Voir Relecture et publication.
Supprimer un brouillon ou un document
Seul un gestionnaire peut supprimer un brouillon ou un document. Les trois points au bout de la ligne d'un brouillon, sous Outputs, correspondent au bouton nommé Actions for draft suivi du titre du brouillon. Un brouillon approuvé ne peut pas être supprimé : sa ligne ne comporte pas ces trois points.
Supprimer un brouillon
Un brouillon qui n'est pas approuvé peut être supprimé avec son contenu.
- Ouvrez le document et sélectionnez Document details.
- Sous Outputs, sélectionnez les trois points au bout de la ligne du brouillon.
- Sélectionnez Delete draft (supprimer le brouillon).
- Dans Delete draft?, sélectionnez Delete.
Le message « Draft deleted » s'affiche. Le brouillon et son contenu sont définitivement supprimés.
Supprimer un document ne le dépublie pas. Un document publié reste accessible à ses lecteurs : pour le retirer, dépubliez-le d'abord (voir Relecture et publication).
Supprimer un document
Supprimer un document supprime ses sections et tous ses brouillons non approuvés.
- Ouvrez le document.
- Sélectionnez le bouton Document actions (trois points) en haut à droite.
- Sélectionnez Delete document.
- Dans Delete document?, sélectionnez Delete.
Le message « Document deleted » s'affiche et la liste s'ouvre. Les brouillons approuvés sont conservés : ils figurent sous Unfiled drafts (brouillons non classés), en bas de la liste, où ils peuvent toujours être ouverts.
Delete document n'est pas proposé tant qu'un brouillon du document est en cours de génération ou d'import.
Vérifier où un fichier ou une procédure est utilisé
Un document peut citer un fichier du produit et intégrer une procédure. Avant la suppression d'un fichier ou d'un schéma de Sources, la confirmation affiche le rapport Where this is used (où cet élément est utilisé). Avant la suppression d'une procédure, elle indique en une phrase quels documents l'intègrent. Cette confirmation est illustrée dans Produits pour un fichier et dans Procédures pour une procédure.
- Le rapport regroupe ce qui utilise l'élément sous Procedures, Published documents et Drafts. Chaque carte désigne un document, un brouillon ou une procédure, ainsi que les endroits concernés.
- Open document, Open section, Open draft et Open procedure ouvrent cet endroit dans un nouvel onglet, pour que vous puissiez d'abord le corriger.
- Why is this listed? (pourquoi cet élément figure-t-il ici ?) explique la présence d'une ligne dans le rapport.
- Lorsque rien n'utilise l'élément, le rapport indique « No procedure, document or draft uses this. » (aucune procédure, aucun document ni aucun brouillon ne l'utilise).
Delete file ou Delete procedure supprime alors l'élément. Les documents et les brouillons conservent leur texte, mais une citation perd le fichier sur lequel elle s'appuie.
Ce que l'Assistant lit d'autre
L'Assistant rédige à partir des sources du produit. Dans la section Sources, deux autres éléments peuvent être ajoutés à son intention : Link a product (lier un produit), sous Linked products, lui permet de lire aussi les sources d'un autre produit, par exemple un modèle précédent, et Connect repository (connecter un dépôt), sous Code, connecte un dépôt GitHub ou GitLab, qu'il se contente de lire. Lorsqu'un produit est lié, la phrase sous le titre de la page Documentation se termine par « The Assistant also sees 1 linked product. » (l'Assistant voit aussi 1 produit lié).