Glossaire
Référence
Définitions des termes de rédaction technique et de rédaction structurée utilisés dans ce manuel, chacun relié à l'article qui l'approfondit.
Des définitions rapides pour les termes utilisés dans ce manuel. Chaque entrée est reliée à l’article qui approfondit le concept - cette page est faite pour la consultation, pas pour l’apprentissage d’un sujet depuis le début.
- Branche
- Ligne de travail parallèle dans un système de gestion de versions : les modifications faites sur une branche restent isolées jusqu’à leur relecture et leur fusion dans la ligne principale, ce qui permet de faire avancer en même temps plusieurs rédacteurs, versions ou langues. Voir utiliser les branches des systèmes de gestion de sources.
- CI/CD (intégration continue et livraison continue)
- Automatisation qui vérifie chaque modification dès qu’elle est proposée (intégration continue), puis publie le résultat une fois les contrôles réussis (livraison continue). En docs-as-code, un pipeline CI/CD compile la documentation, exécute des tests, comme la vérification des liens et des schémas, et déploie le site. Voir un pipeline CI/CD concret pour la documentation.
- CMS (Content Management System)
- Un outil qui ajoute workflow et verrouillage des fichiers à la gestion de contenu, au prix de compromis de fiabilité par rapport à une gestion de versions simple. Voir les CMS : le workflow en prime, mais une fiabilité à tester.
- Commit
- Instantané enregistré des modifications apportées à un dépôt Git, accompagné d’un auteur, d’une date et d’un message qui explique le changement. La suite des commits forme l’historique du projet, point de départ des branches et base de comparaison pour les relecteurs et les traducteurs. Voir Git : du fichier au contenu.
- Concept, tâche, référence
- Les trois types d’information de base de DITA XML : un concept introduit ou explique une idée, une tâche est une procédure numérotée, une référence est un contenu de consultation comme une liste de paramètres. Les articles de ce manuel sont eux-mêmes étiquetés selon ces trois types. Voir formats structurés et non structurés.
- Texte conditionnel
- Contenu marqué comme ne s’appliquant qu’à un public, une version de produit ou un livrable donnés, afin qu’une même source puisse être filtrée à la compilation pour produire des documents différents. DITA XML le met en œuvre avec les fichiers ditaval ; des moteurs de modèles comme Jinja font de même pour les formats texte. Voir créer des documents différents à partir des mêmes sources via Jinja.
- Conref
- Un mécanisme DITA XML de réutilisation d’un bloc de contenu par référence : le contenu d’un nœud cible est remplacé par le contenu d’un nœud source à la compilation. Voir partager des blocs d’information atomiques avec les conref.
- Réutilisation du contenu (réutilisation de contenu)
- Rédiger une information une seule fois et l’employer à plusieurs endroits ou dans plusieurs livrables plutôt que de la recopier : une correction faite une fois s’applique partout. Les conrefs, le texte conditionnel et le single-sourcing sont autant de moyens d’y parvenir. Voir cas concret : documentation de NuFirewall.
- DITA-OT (DITA Open Toolkit)
- Moteur de publication open source qui transforme des sources DITA XML, assemblées par un ditamap, en formats cibles comme le PDF (via XSL-FO) ou le HTML. Voir didacticiels DITA XML et XSL-FO.
- Ditamap
- Un fichier externe de table des matières qui assemble des topics DITA XML en document, sans que les topics eux-mêmes aient besoin de connaître leur position dans ce document.
- Ditaval
- Un fichier de filtre DITA XML qui inclut ou exclut du contenu marqué avec des attributs correspondants au moment de la compilation - le mécanisme derrière le texte conditionnel de DITA.
- DocBook
- Langage de balisage XML sémantique destiné à la documentation technique, organisé en livres, chapitres et sections plutôt qu’en topics typés. Antérieur à DITA XML, il sert de point de comparaison habituel lors du choix d’un format structuré. Voir du document à la base documentaire modulaire.
- Docs-as-code
- Traiter la documentation comme du code source : formats texte, gestion de versions, revue de code et CI/CD, plutôt qu’un processus de publication séparé. Voir adopter le docs-as-code.
- DITA XML
- Une architecture de rédaction structurée et modulaire, construite autour de la typologie concept/tâche/référence et de la réutilisation de contenu via conrefs et ditamaps. Voir format structuré DITA XML.
- DTD (Document Type Definition)
- Le plus ancien langage de schéma XML : il déclare les éléments et les attributs qu’un document peut contenir, et dans quel ordre. DITA XML est distribué avec des DTD aussi bien qu’avec des schémas XSD.
- Typage de l’information
- La discipline consistant à classer le contenu selon son objectif communicatif (concept, tâche, référence) plutôt que de rédiger une prose indifférenciée. Voir formats structurés et non structurés.
- llms.txt
- Fichier texte placé à la racine de ce site (
/llms.txt) qui suit la convention llms.txt : une table des matières concise qui oriente les programmes et les agents IA vers les versions lisibles par machine de ce manuel (Markdown par page, index JSON et fichiers regroupant tout le corpus). Voir l’API de ce manuel. - Documentation lisible par machine
- Documentation publiée sous une forme que des programmes peuvent consommer directement (fichiers Markdown, index JSON ou corpus en texte brut), en plus des pages HTML rendues pour les lecteurs humains. Ce manuel génère les deux à partir des mêmes sources au moment de la génération. Voir l’API de ce manuel.
- Markdown
- Langage de balisage léger en texte brut, où la mise en forme s’exprime par une ponctuation simple, par exemple un
#en début de ligne pour un titre. Facile à rédiger et à relire sous gestion de versions, il n’impose aucun schéma : les équipes docs-as-code compensent par des modèles et des contrôles automatisés. Ce manuel est rédigé en MDX, une variante de Markdown. Voir choisir un modèle de rédaction. - Minimalisme (rédaction minimaliste)
- Une section tâche ne contient que ce qui est nécessaire pour accomplir la tâche - prérequis, étapes et quelques éléments étroitement liés - le contenu conceptuel et de référence étant placé ailleurs. Voir formats structurés et non structurés.
- Documentation modulaire
- Un contenu construit à partir de petites unités réutilisables et autonomes (topics ou modules) assemblées à la demande, plutôt que rédigé sous forme de documents monolithiques. Voir du document à la base documentaire modulaire.
- OpenAPI
- Format normalisé et lisible par machine (YAML ou JSON) qui décrit une API HTTP : endpoints, paramètres, schémas de requête et de réponse, codes d’état. La documentation de référence peut en être générée ; le rédacteur y ajoute les conseils d’usage que la description ne peut pas porter. Voir modèle : documentation d’API.
- Pull request
- Demande d’intégration des modifications d’une branche dans la ligne principale, présentée sous forme de différences à relire : les relecteurs commentent, les contrôles automatisés s’exécutent et l’approbation est tracée avant la publication. GitLab parle de merge request. Voir création du contenu.
- Référentiel
- L’endroit où une équipe documentaire conserve ses sources : répertoires partagés, base de données d’un CMS ou système de gestion de versions comme Git, qui conserve en outre l’historique complet de chaque fichier. Un référentiel Git est aussi appelé dépôt. Voir référentiel.
- reStructuredText
- Langage de balisage en texte brut issu de l’écosystème Python, plus riche que Markdown (directives, rôles, renvois) et format source natif du générateur de documentation Sphinx. Voir insérer automatiquement des données dans un fichier reStructuredText.
- Single-sourcing
- Générer plusieurs livrables (PDF, HTML, formats d’aide) à partir d’une source unique, plutôt que de maintenir une source séparée par format de sortie. Voir format cible.
- Format source
- Le format dans lequel le contenu est rédigé, par distinction avec le format cible vers lequel il est publié - la recette contre le plat. Voir format source.
- Rédaction structurée
- Rédiger un contenu dont le balisage encode le sens (ceci est un avertissement, ceci est une étape) plutôt que la seule apparence visuelle - permettant un traitement automatisé, une réutilisation et des contrôles de cohérence que les formats non structurés ne permettent pas. Voir formats structurés et non structurés.
- Format cible
- Le format réellement consommé par le lecteur - PDF, HTML, aide compilée - généré à partir du format source. Voir format cible.
- Communication technique
- La discipline plus large qui couvre tout le cycle de vie du produit et touche le grand public, les prospects et les journalistes - par distinction avec la rédaction technique, qui produit la documentation produit destinée aux utilisateurs après la vente. Voir de la rédaction à la communication technique.
- Topic
- La plus petite unité d’information autonome et titrée en DITA XML, typée comme concept, tâche ou référence et assemblée en documents via des ditamaps.
- Gestion de versions
- Enregistrement de chaque modification d’un ensemble de fichiers, qui permet de restaurer n’importe quel état antérieur, de comparer les changements et de travailler à plusieurs en parallèle. Git est le logiciel de gestion de versions le plus répandu ; en docs-as-code, la documentation est placée sous gestion de versions à côté du code du produit. Voir les systèmes de gestion de versions.
- WYSIWYG
- Abréviation de what you see is what you get (« ce que vous voyez est ce que vous obtenez ») : l’édition se fait dans une vue qui ressemble à la page finale, comme dans un traitement de texte, et la mise en page est appliquée à la main. À l’inverse, la rédaction structurée balise le sens du contenu et applique la mise en page automatiquement à la publication. Voir format source.
- XSD (XML Schema Definition)
- Le langage de schéma XML du W3C, lui-même écrit en XML. Les schémas XSD de DITA XML définissent les éléments autorisés dans chaque type de topic ; un fichier qui ne les respecte pas échoue à la validation, ce qui limite aussi ce que les conrefs et le texte conditionnel peuvent produire. Voir cas concret : documentation de NuFirewall.
- XSL-FO
- Un langage de feuilles de style pour transformer et mettre en page du contenu XML pour une sortie impression/PDF, couramment associé aux pipelines de publication DITA XML. Voir didacticiels DITA XML et XSL-FO.
- XSLT (XSL Transformations)
- Langage de transformation de documents XML en d’autres documents XML, HTML ou texte. Les chaînes de publication XML comme le DITA Open Toolkit utilisent des feuilles de style XSLT pour produire du HTML, ou du XSL-FO pour la sortie PDF. Voir format source.