Du document à la base documentaire modulaire
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 du 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 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 ou un VCS. Le capital immatériel de la société est ainsi préservé.
Un langage à balises
Section intitulée « 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 :
| Rôle | Description |
|---|---|
| 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
Typologie de haut niveau de l’information
Section intitulée « 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
Section intitulée « 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 :
| Document | Contenu |
|---|---|
| Guide de l’utilisateur | Thèmes systématiquement organisés en concept et procédures pas à pas |
| Document de présentation | Concepts |
| Quikstart | Procédures pas à pas |
| Manuel de référence | Informations de référence |
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
Section intitulée « 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.
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
Section intitulée « 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 conref, similaire au mécanisme Xinclude proposé par DocBook.
Gérer son contenu DITA XML avec ou sans CMS ?
Section intitulée « 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 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 part 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, de Subversion ou de SourceSafe. À 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. Ainsi, Epson America a pu réutiliser jusqu’à 90 % du 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