DITA XML permet de passer du livre monolithique à la base documentaire modulaire pour réutiliser les topics, optimiser la traduction et publier en multicanal.
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éeRé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 dans le glossaire →DITA XMLUne 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 dans le glossaire → 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.
Une Documentation modulaireUn 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 dans le glossaire → 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érentielL'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 dans le glossaire → unique, tel qu’un ECM ou un VCS. Le capital immatériel de la société est ainsi préservé.
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 :
Rédacteur technique
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, 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.
Utilisateur
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.
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, DocBookLangage 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 dans le glossaire → 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 Typage de l'informationLa 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 dans le glossaire → 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.
Les briques d’information peuvent être assemblées à la demande dans des structures de table des matières externes, les DitamapUn 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.Voir dans le glossaire →.
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 :
Guide de l'utilisateur
Contenu : Thèmes systématiquement organisés en concept et procédures pas à pas
Document de présentation
Contenu : Concepts
Quickstart
Contenu : Procédures pas à pas
Manuel de référence
Contenu : Informations de référence
Une ditamap organise les TopicLa 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.Voir dans le glossaire → 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 ditamap1, il doit pouvoir être également utilisé sans modification dans la ditamap2, 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-sourcingGé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 dans le glossaire → 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.
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 cibleLe format réellement consommé par le lecteur — PDF, HTML, aide compilée — généré à partir du format source.Voir dans le glossaire →. 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.
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 ConrefUn 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 dans le glossaire →, similaire au mécanisme Xinclude proposé par DocBook.
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 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 (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 dans le glossaire →, 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.