# Du document à la base documentaire modulaire ## Définition Le modèle du livre est encore prédominant pour créer et gérer l'information. Mais le contenu d'entreprise est souvent disséminé dans de nombreux documents, sous des formats hétérogènes. Ceci se traduit par des doublons, des incohérences, un coût de mise à jour et de traduction élevé, et des retards de livraison. Le rédacteur technique dispose cependant d'autres modèles, plus efficaces. Le format de rédaction structurée DITA XML propose de passer du modèle du livre à celui de la base documentaire modulaire. Le contenu d'entreprise repose sur des briques uniques, qui peuvent être assemblées dynamiquement, à la demande, pour produire des documents sous différents formats cibles. > **Schéma: Une documentation modulaire offre une souplesse inégalée** > > Schéma opposant la documentation monolithique, un bloc unique et indivisible, à la documentation modulaire, assemblée à la demande à partir de plusieurs blocs. **Une documentation modulaire offre une souplesse inégalée.** Le volume de contenu source est minimisé, ce qui diminue les coûts de création, mise à jour et traduction du contenu d'entreprise. De plus, le rédacteur technique peut gérer les processus de rédaction, validation et traduction module par module. Les workflows peuvent ainsi être parallélisés, ce qui réduit les délais de mise sur le marché. Les fichiers DITA XML peuvent en outre être aisément centralisés sous un référentiel unique, tel qu'un ECM (système de gestion de contenu) ou un VCS (logiciel de gestion de versions). Le capital immatériel de la société est ainsi préservé. ## Un langage à balises DITA XML est un langage à balises : le rédacteur technique structure l'information dans des fichiers sources sans mise en page, similaires aux fichiers sources de code informatique. L'utilisateur reçoit un document cible, par exemple un fichier PDF, où les balises sont remplacées par une mise en forme typographique. Si votre entreprise fournit à ses clients une documentation technique au format MS Word, le rédacteur technique et l'utilisateur disposent des mêmes supports d'information (il n'y a pas de différenciation entre le fichier source et le fichier cible). Ce qui semble a priori la solution la plus simple s'avère cependant peu efficace en termes de productivité de l'équipe de rédaction technique et de structuration de l'information. Avec un format texte tel que DITA XML, le rédacteur technique et le lecteur disposent de supports largement différents : ### '> Le rédacteur technique manipule des fichiers sources ; il utilise les balises pour construire le document en marquant les éléments d'information qu'il crée ou réutilise. Les balises sont imbriquées comme des poupées russes organisées selon une syntaxe rigoureuse. Le fichier source n'est pas au format WYSIWYG : la mise en page sera appliquée lors de la transformation des fichiers sources en fichiers cibles (autrement dit, lors de la génération des livrables). Certains logiciels graphiques tels que XMetaL, Oxygen ou FrameMaker structuré proposent le format WYSIWYM (what you see is what you mean), où les balises sont remplacées à l'écran par une mise en forme générique, différente de l'aspect final du document. L'intérêt d'un langage à balises est de voir exactement ce que l'on fait en manipulant soi-même les balises sans déléguer l'interprétation à un logiciel graphique. ### '> Seul le contenu est présenté au lecteur dans le fichier cible ; le texte marqué par des balises dans les fichiers sources a une mise en valeur typographique dont le sens est explicité dans la section Conventions typographiques du document final. Un fichier source DITA XML mélange du texte et des balises, délimitées par les signes < et >. Le texte proprement dit est encapsulé dans un jeu de balises ouvrantes de type et de balises fermantes de type selon le schéma texte. Tout texte entré hors d'une balise ouvrante et fermante est incorrect et produit un fichier non valide. ## Typologie de haut niveau de l’information DITA XML propose au rédacteur technique une typologie de haut niveau qui est une véritable aide à la structuration du contenu. S'il crée un nouveau document au format FrameMaker, DocBook ou traitement de texte, le rédacteur technique se trouve face à une page blanche. Selon sa rigueur professionnelle, l'information transmise à l'utilisateur oscillera entre les deux pôles suivants : | Élément / Concept | Description | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------| | Organisation rationnelle | L'utilisateur dispose d'un accès séquentiel rapide et aisé à l'information dont il a besoin. | | Magma informatif | L'utilisateur doit lire intégralement toute une section, voire le document en sa totalité pour espérer trouver des renseignements utiles. | | concept (DITA XML) | Texte généraliste du type introduction ou présentation. | | task (DITA XML) | Procédure pas à pas destinée à réaliser une tâche. | | reference (DITA XML) | Information de référence du type explication de paramètres de commandes. | Chacune de ces catégories de haut niveau propose un jeu de balises de plus bas niveau qui lui est propre. Si le rédacteur technique rédige un document technique, il y a toutes les chances pour que l'information qu'il a collectée et qu'il doit organiser fasse partie de l'une de ces trois catégories. Cette division en types d'information oblige donc d'entrée de jeu le rédacteur technique à structurer l'information. L'utilisateur y gagne en facilité et rapidité d'accès à l'information et en utilisabilité globale de la documentation technique. ## Organisation à la demande du contenu Les briques d'information peuvent être assemblées à la demande dans des structures de table des matières externes, les *ditamap*. L'organisation de l'information sous DITA XML n'est pas figée. Les briques peuvent être organisées dans différentes structures hiérarchiques, selon l'évolution des besoins. Si le rédacteur technique a pris soin de construire des briques d'information atomiques et génériques, il peut, à l'instar d'un constructeur automobile proposant sans cesse de nouveaux modèles par assemblage d'éléments standardisés, proposer par exemple les documents suivants : ### '> **Contenu :** Thèmes systématiquement organisés en concept et procédures pas à pas ### '> **Contenu :** Concepts ### '> **Contenu :** Procédures pas à pas ### '> **Contenu :** Informations de référence > **Schéma: Une ditamap organise les topics en arborescence** > > Arborescence de la ditamap du guide de l'utilisateur : un topic concept de présentation, un sous-groupe Installation contenant un concept de prérequis et une tâche d'installation, puis un topic de dépannage. **Une *ditamap* organise les topics en arborescence.** Pour ce faire, le rédacteur technique prendra soin de placer les éléments liés à un contexte particulier dans les structures *ditamap* et non dans les fichiers de contenu DITA XML. En particulier, les références croisées doivent être indiquées dans une *reltable* placée dans la *ditamap* : si le document *A* doit renvoyer au document *B* dans la *ditamap* *1*, il doit pouvoir être également utilisé sans modification dans la *ditamap* *2*, où le document *B* n'est pas inclus. L'organisation des répertoires de travail doit également permettre l'utilisation de liens relatifs, notamment vers les images, qui ne seront jamais cassés. ## Le single-sourcing : un format source, plusieurs formats cibles Le *single-sourcing* est un sujet qui a longtemps divisé les rédacteurs techniques : des supports de rédaction technique différents, tels qu'une aide en ligne et un manuel imprimé, doivent-ils proposer un contenu radicalement différent ou peuvent-ils être générés à partir du même contenu source ? Les contraintes de productivité et la réduction des coûts aidant, le débat a été tranché en faveur du *single-sourcing*. Le gain qualitatif, discutable, ne compense pas le coût de créer, maintenir et traduire une version source différente pour chaque version cible. > **Schéma: Un seul jeu d'informations, une multiplicité de formats de sortie** > > Schéma montrant DITA XML comme point central alimentant cinq formats de sortie, PDF, site web, traitement de texte, JavaHelp et aide Windows. **Un seul jeu d'informations, une multiplicité de formats de sortie** Si le rédacteur technique pratique le *single-sourcing*, il doit cependant sélectionner en début de projet le paradigme sur lequel il se base : le livre ou l'aide en ligne. Pendant longtemps, les outils proposés reposaient soit sur un document de type livre (MS Word, ou FrameMaker, essentiellement) qui pouvait être exporté au format d'aide en ligne, soit sur un fichier source (RTF) d'aide Windows, pour générer un PDF. Une forte perte d'information de navigation (index, références croisées, liens, etc.) intervenait souvent lors de l'exportation. DITA XML propose un modèle agnostique quant au format cible. Les fichiers sources, bien que basés sur un modèle modulaire proche de celui de l'aide en ligne, peuvent facilement être exportés sous forme de fichier PDF, d'aide en ligne, de pages HTML liées ou autre, sans aucune perte d'information. ## Les topics, modules d’information de base DITA XML Les topics sont les plus petites unités d'information autonomes gérées par DITA XML. Chaque *topic* a un titre et un corps de texte. Il ne traite que d'un seul sujet. Il appartient donc au rédacteur technique de se baser sur la modularité proposée par DITA XML pour bien structurer l'information. C'est cette autonomie, et non le simple découpage d'un document en fichiers plus petits, qui rend une documentation modulaire : voir [la documentation modulaire dans l'historique du site](https://docs.redaction-technique.org/fr/site-history/#methodes-de-la-redaction-technique). Les *topics* sont sémantiquement typés. Il existe idéalement un type de *topic* par type d'information. DITA XML propose par défaut des *topics* adaptés à la documentation des logiciels (description de concepts et de tâches, liste de commandes, etc.), mais de nouveaux types de *topics* peuvent être créés pour répondre à d'autres besoins. Les *topics* sont une des différences principales entre DITA XML et DocBook, qui ne propose pas de typologie des briques d'information. Les *topics* sont généralement stockés à plat dans des répertoires divisés par type de *topic*. Ils sont organisés hiérarchiquement dans des fichiers *ditamap* et peuvent être partagés entre différents documents. Les titres des modules ne sont pas affectés d'un niveau de titre. La structure des modules étant parfaitement homogène, un module peut avoir un niveau 3 dans un document donné, et un niveau 1 dans un autre document, sans qu'il y ait besoin de modifier en quoi que ce soit les *topics*. Les unités d'information atomiques telles que des remarques, des paragraphes, voire des phrases ou des segments de phrase, qui ne peuvent pas être munis d'un titre, ne forment pas des *topics*. Elles peuvent être cependant partagées via le mécanisme *conref*, similaire au mécanisme *Xinclude* proposé par DocBook. ## Gérer son contenu DITA XML avec ou sans CMS ? L'architecture DITA XML ne propose pas de mécanisme de workflow documentaire natif. Les workflows sont pourtant un élément important d'un processus efficace de gestion du cycle de vie du contenu. Les CMS (Content Management System) gèrent également les métadonnées, ce qui permet une recherche plus efficace de l'information existante, et les rétroliens. La plupart des entreprises sont réticentes à mettre en place des CMS, outils dédiés aux workflows. Elles ont d'ailleurs parfois connu des échecs de mise en place de telles solutions par le passé. De plus, l'un des grands avantages de DITA XML, c'est de s'intégrer directement dans le système d'information en place. Chez les éditeurs de logiciels, notamment, rien de plus facile que de venir se greffer sur le système de gestion des sources en place, qu'il s'agisse de Git ou de Subversion. À budget quasi nul. Raison de plus pour ne pas investir du temps et de l'argent dans un CMS. Les gains de productivité spectaculaires reportés par certaines entreprises suite à la mise en place d'un CMS DITA XML ont cependant de quoi faire réfléchir. Certaines ont ainsi pu réutiliser une part importante de leur contenu existant sur de nouveaux projets. Si l'on opte pour un CMS, celui-ci doit clairement supporter DITA XML : on ne gère pas un jeu de briques d'information comme un document monolithique. Adieu donc SharePoint ou Alfresco, il faut se tourner vers des solutions dédiées telles que Componize ou DocZone. Quel que soit le choix initial, il est possible à tout instant de changer de stratégie, sans remettre en cause l'existant. L'architecture DITA XML n'est en effet liée à aucun référentiel particulier. Rien n'interdit donc de commencer à gérer ses projets sans CMS, puis d'avoir recours à une telle solution si les bénéfices de ce choix deviennent manifestes. **Voir aussi** - [Git : du fichier au contenu](https://docs.redaction-technique.org/fr/tech-writing-process/git-from-file-to-content/) ## Articles connexes - [Formats structurés et non structurés](https://docs.redaction-technique.org/fr/formats/structured-vs-unstructured-formats/) - [Formats et outils](https://docs.redaction-technique.org/fr/costs/formats-and-tools/) - [Didacticiels DITA XML et XSL-FO](https://docs.redaction-technique.org/fr/tutorials/dita-xml-xsl-fo-tutorials/) --- Source: https://docs.redaction-technique.org/fr/formats/modular-documentation/