Réduire les coûts et améliorer la qualité de la documentation avec DITA XML

Darwin Information Typing Architecture (DITA), est une architecture XML destinée à la création de documents structurés et modulaires. Elle diminue les coûts de production et de traduction, réduit les délais de mise sur le marché et améliore la qualité.

Les impatients trouveront sur le site de ressources pour le rédacteur technique comment mettre en place une chaîne de création et de publication DITA XML libre. Cette chaîne repose sur Emacs et le mode nXML (avec des schémas Relax NG modifiés) et DITA Open Toolkit. La suite de la dépêche détaille l'architecture DITA.

Sommaire

• Des documents à la base documentaire
• DocBook et DITA : le livre et le réseau
  • De la modularisation au partage de l'information
• DITA
  • Un standard
  • Rédaction structurée
  • Séparation du format source et du format cible
  • Unités de base DITA : les topics
    • Topic
    • Concept
    • Task
    • Reference
  • Spécialisation
  • Typologie de l'information
  • Structure de table des matières : map
  • Partager des unités d'informations atomiques avec les conref
  • Texte conditionnel
    • Exemple : documentations d'une version libre et propriétaire d'un même logiciel
• Un format adapté aux entreprises de toutes tailles
• DITA Open Toolkit
• Cas concret : documentation de NuFirewall
• Bibliographie

Des documents à la base documentaire

Dans beaucoup d'entreprises, de nombreux intervenants gèrent chacun leurs propres fichiers de traitement de texte ; leurs documents contiennent beaucoup de parties communes, qui sont dupliquées en différents exemplaires. Ceci présente un fort risque d'erreurs et un coût de maintenance et de traduction élevé.

Au lieu de disséminer l'information dans des fichiers différents présentant souvent des doublons et des incohérences, DITA propose de créer une base documentaire unique reposant sur des fichiers modulaires, à partir de laquelle pourront être générés à la demande des documents destinés à différents publics. Avantages :

• les informations en doublon sont supprimées ou fortement réduites,
• le volume de contenu source est minimisé, ce qui diminue les coûts de création, mise à jour et traduction,
• chaque module d'information peut être traduit dès qu'il est validé, avant l'achèvement du document final, ce qui réduit les délais de mise sur le marché des versions traduites,
• chaque public dispose de toute l'information et rien que l'information dont il a besoin,
• tous les documents contiennent des informations cohérentes,
• le contenu est centralisé et peut aisément être géré sous un système de gestion de versions et sauvegardé.

DocBook et DITA : le livre et le réseau

Lorsque j'ai commencé à pratiquer la communication technique, certains rédacteurs défendaient le fait que chaque type de support de communication doit présenter un contenu spécifique. Les tenants du single-sourcing, dont je fais partie, souhaitent au contraire partager au maximum le contenu source et en automatiser la publication sous différents formats cibles, aide en ligne et manuel PDF, essentiellement.

Cependant, il est vrai qu'une aide en ligne et un manuel ont des structures différentes :

• un manuel est un ensemble de sections organisées de manière hiérarchique et linéaire,
• une aide en ligne est un ensemble de modules d'information autonomes qui peuvent être consultés de manière non hiérarchique et non linéaire.

Poussé à son extrême :

• un livre est court et la redondance de l'information est minimale : le public est supposé lire le manuel en entier,
• une aide en ligne agrège dynamiquement uniquement les informations dont le lecteur a besoin.

Évidemment, les frontières sont moins nettes et les deux modèles se mêlent toujours dans une certaine mesure :

• organisation hiérarchique sous forme de table des matières d'une aide en ligne,
• index d'un manuel,
• liens d'une aide en ligne ou références croisées d'un manuel,
• recherche en plein texte pour les manuels fournis en PDF, etc.

Il reste que si l'on pratique le single-sourcing, il faut choisir dès le début du projet le paradigme sur lequel on se base :

• soit créer du contenu basé sur le modèle du livre, puis le modulariser pour créer une aide en ligne,
• soit créer des modules d'information autonomes, puis les regrouper en manuel.

Lorsque j'ai commencé à pratiquer le single-sourcing, la plupart des outils disponibles étaient basés sur des macros qui partaient d'un document Word, puis exportaient le contenu au format source de l'aide Windows (RTF), ou partaient de ce format source pour générer un document Word.

Vous vous en doutez, le processus était particulièrement inélégant et générateur d'entropie : de nombreuses informations de structure (liens, organisation hiérarchique de l'information, etc.) étaient souvent perdues en cours de route. FrameMaker, logiciel de rédaction technique respectable, proposait également d'exporter un document de type livre vers une aide en ligne, mais toujours à l'aide de surcouches plus ou moins élégantes et fiables.

De la modularisation au partage de l'information

Indépendamment du choix des outils, le modèle de l'aide en ligne se base sur des modules d'information dont la structure est identique. Il est donc plus facile de réorganiser l'information au fur et à mesure de l'ajout, de la suppression ou de la modification de modules, ou pour cibler des besoins spécifiques.

En outre, une fois l'information divisée en modules de structure homogène, il devient beaucoup plus facile de la réutiliser :

• si un seul fichier contient tout un livre, la répétition d'une partie de contenu doit se faire par duplication (copier-coller) ; la mise à jour ou la traduction de ce module devient donc fastidieuse et est une source d'erreurs importante ;
• si un document est une agrégation de fichiers autonomes, la répétition dans le document final d'une partie de contenu se fait par insertion de liens vers un fichier unique ; la mise à jour ou la traduction de cette partie de contenu ne doit donc être effectuée qu'une seule fois, ce qui diminue les coûts et améliore la qualité.

DITA

Un standard

Créée initialement par IBM, l'architecture DITA est aujourd'hui un standard géré par OASIS.

Rédaction structurée

À la différence d'autres systèmes de composition de documents, tels que les traitements de texte ou les logiciels de PAO, DITA, comme DocBook, se concentre sur la sémantique du contenu plutôt que sur la mise en page. Le fond plutôt que la forme.

Supposons que vous vouliez mettre en gras les mots qui correspondent à une option de l'interface graphique dans le PDF fourni aux utilisateurs :

• sous un traitement de texte, vous mettez ce mot en gras,
• en HTML, vous incluez ce mot entre balises <strong> et </strong>,
• sous DITA, vous incluez ce mot entre balises <uicontrol> et </uicontrol> ; c'est une feuille de style qui applique le corps gras au texte cible.

Même si d'autres éléments, par exemple, des options de ligne de commande, apparaissent en gras dans le document cible, ils sont différenciés dans les fichiers source.

Avantages :

• vous pouvez aisément changer la mise en forme des options de l'interface dans un nombre illimité de documents,
• si d'autres éléments sont en gras, leur mise en forme peut facilement être modifiée, et celle des options de l'interface rester inchangée,
• vous pouvez facilement extraire toutes les options de l'interface à partir d'un nombre illimité de documents, par un simple grep par exemple.

Séparation du format source et du format cible

DITA pousse très loin la séparation du fond et de la forme. À partir du même format source, de nombreux formats cibles peuvent être générés : PDF, XHTML, HtmlHelp, troff, DocBook, etc.

Unités de base DITA : les topics

Les topics sont des modules d'information disposant d'un titre et d'un corps de texte. Ils doivent traiter d'un seul sujet. Si le topic que vous créez contient deux sujets, scindez-le en deux nouveaux topics - DITA est une architecture de rédaction structurée, mais il faut quand même que vous structuriez vous-même votre pensée ;-). Une remarque ou un paragraphe unique sont en revanche des unités d'information atomiques qui ne peuvent être à elles seules un topic.

Topic

Sections génériques, peu contraignantes sur le plan de la structure.

Exemple de structure d'un topic :

       +----+title
       |    +
       |    +----titlealts
       |    +----shortdesc
       |
       |          +-----------author
       |          |+----------source
       |          |+----------publisher
       |          |+----------copyright
  topic++--+prolog++----------critdates
       +          ++----------permissions
       |          |+----------metadata
       |          +-----------resourceid
       |
       |
       +----body
       |
       +----related-links

Concept

Sections destinées à présenter une introduction des sections task ou reference.

Exemple de structure d'un concept :

            +-title
            |
  concept--shortdesc
            |
            +-conbody

Task

Sections destinées à présenter des procédures pas à pas pour effectuer une tâche. Elles incluent des parties :

• contexte,
• prérequis,
• résultat,
• exemple,
• étapes suivantes.

Exemple de structure d'une task :

       +----+title
       |    |
       |    +----titlealts
       |    +----shortdesc
       |                                               +---boolean
       +----prolog                                     |
       |            +-prereq          +hazardstatement +---data
       |            |                 |                |
       |            |-example      +---cmd+------------+---uicontrol
  task +----taskbody+              |  |                |
       |            |-context      |  +note            +---menucascade
       |            |              |                   |
       |            |-steps--step--+--choices          +---userinput
       |            |              |
       |            |-result       +--stepxmp
       |            |              |
       |            +-postreq      +--substeps
       |                           |
       +----related-links          +--info

Reference

Sections destinées à présenter des listes d'informations (commandes de langage de programmation, recettes de cuisine, bibliographies, catalogues, etc.).

Exemple de structure d'une section reference :

           +---title
           |
           |
  reference+
           |
           |          +---refsyn               +---proptypehd
           |          |                        |
           +---refbody+---properties---prophead+---propvaluehd
                      |                        |
                      +---section              +---propdeschd

Spécialisation

DITA est initialement conçue pour la documentation des logiciels, mais il est possible de créer de nouveaux topics, appelés spécialisations, pour traiter d'un sujet spécifique, par exemple l'aéronautique. Il suffit de spécifier les différences entre l'ancien et le nouveau topic, la plupart des caractéristiques du nouveau topic étant héritées de celui dont il dérive.

Typologie de l'information

Les topics sont typés selon l'information qu'ils contiennent : description, procédure, etc. La sémantique DITA est donc à plusieurs niveaux :

• termes (option d'interface graphique, adresse postale, etc.),
• paragraphes (prérequis, étape de procédure, etc.),
• modules d'information (topics, concepts, tasks).

DITA invite à choisir un schéma différent pour chaque type d'information. Les procédures doivent être rédigées sous un schéma de type task et ne peuvent pas être associées à un schéma topic, par exemple, ce dernier n'acceptant pas les balises de procédures pas à pas <step>.

DITA est donc une aide à la structuration des documents. Si je commence une rubrique de type concept et que de fil en aiguille j'en viens à rédiger une procédure pas à pas, le garde-fou du schéma XML m'oblige à créer une section task distincte. Je peux alors présenter l'information de manière plus claire pour son destinataire puis, par exemple, publier par la suite :

• un guide PDF ne contenant que les concepts du produit comme introduction à son utilisation,
• une aide en ligne ne contenant que les procédures de réalisation de tâches spécifiques.

Structure de table des matières : map

Une map ne contient qu'une série de liens hiérarchisés vers différents topics ou d'autres maps. Il est donc facile de créer différents documents à partir des mêmes fichiers source.

Vous pouvez par exemple générer à partir de sources DITA :

• un manuel de référence présentant toutes les options possibles d'un programme de gestion de réseau,
• un guide de l'administrateur contenant une section présentant les options du programme qui ne concernent que les administrateurs réseau,
• un guide de maintenance contenant une section présentant les options qui ne concernent que les techniciens de maintenance.

Exemple de structure de maps (une map incluse dans une autre et deux maps différentes pointant vers les mêmes fichiers source pour générer des documents distincts) :

  ditamap-1                              ditamap-2
       |                                      |
       +--------topic-1                       |
       +--------topic-2                       |
       +--------ditamap-1-1                   |
       |             +--------task-1----------+
       |             +--------task-2 ---------+
       +--------task-3 -----------------------+
       +--------task-4 -----------------------+
       +--------reference-1

Partager des unités d'informations atomiques avec les conref

Les unités d'information trop petites pour faire l'objet d'une section à part entière peuvent être partagées via le mécanisme des conref, similaire au mécanisme Xinclude utilisé sous DocBook.

Exemple :

un fichier de contenu contient la balise suivante :

     <uicontrol conref="shared.dita#shared/system"/>

À la différence du mécanisme des Xinclude utilisé sous DocBook, la valeur vers laquelle pointe le conref doit se trouver dans un contexte conforme au schéma XML. Par exemple, la valeur associée à l'exemple ci-dessus se trouve dans un fichier shared.dita de type task :

  <?xml version="1.0" encoding="utf-8"?>
  <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA 1.2 Task//EN" "../../dtd/technicalContent/dtd/task.dtd">
  <task id="shared" xml:lang="fr-fr">
    <title>Conref</title>
    <taskbody>
      <steps>
        <step>
          <cmd>
            <menucascade>
              <uicontrol id="system">Système</uicontrol>
            </menucascade>
          </cmd>
        </step>
      </steps>
    </taskbody>
  </task>

Texte conditionnel

DITA permet de filtrer des éléments d'information lors de la génération des fichiers cibles. Elle propose l'utilisation des marqueurs sémantiques suivants :

• audience : les différents publics à qui est destiné l'information, par exemple les utilisateurs finaux ou les ingénieurs système,
• platform : la plateforme ou l'environnement du produit dont traite le document, par exemple le système d'exploitation ou la plateforme matérielle,
• product : par exemple le nom du produit ou sa version,
• rev : le niveau de révision (par exemple, un paragraphe peut avoir l'attribut de révision 1.1) ; ce marqueur est surtout intéressant si l'on ne crée pas de tag des versions de la documentation sous un système de gestion de versions,
• props : un marqueur générique qui peut être spécialisé,
• otherprops : ce que vous voulez !

Ces marqueurs peuvent bien entendu servir à d'autres fins telles que la recherche ou l'indexation. Ils peuvent être utilisés au niveau des topics ou des maps.

Le code source qui contient des marqueurs doit être valide avant exclusion d'une des valeurs. Par exemple, le code suivant est incorrect :

  <step>
    <cmd audience="ose">
     Cliquez sur <uicontrol>Salut</uicontrol>.
    </cmd>
    <cmd audience="non-ose">
     Cliquez sur <uicontrol>Bonjour</uicontrol>.
    </cmd>
    <info>
    Information commune aux deux publics
    </info>
  </step>

En effet, même s'il correspond après filtrage à un code qui serait conforme au schéma task, qui n'accepte qu'une seule balise par balise , il en contient deux avant traitement.

Il faut donc utiliser le code suivant :

  <step audience="ose">
    <cmd>
     Cliquez sur <uicontrol>Salut</uicontrol>.
    </cmd>
    <info>
    Information commune aux deux publics
    </info>
  </step>
  <step>
    <cmd audience="non-ose">
     Cliquez sur <uicontrol>Bonjour</uicontrol>.
    </cmd>
    <info        Information commune aux deux publics
    Information commune aux deux publics
    </info>
  </step>      

quitte à partager la section info par le mécanisme des conref :

  <step audience="ose">
    <cmd>
     Cliquez sur <uicontrol>Salut</uicontrol>.
    </cmd>
    <info conref="shared.dita#shared/system">
    </info>
  </step>
  <step>
    <cmd audience="non-ose">
     Cliquez sur <uicontrol>Bonjour</uicontrol>.
    </cmd>
    <info conref="shared.dita#shared/system">
    </info>
  </step>      

Les blocs d'information traités par les conref sont donc en moyenne plus grands que ceux gérés par les Xinclude. Leur utilisation demande plus de réflexion, voire d'acrobaties, dans la structuration des informations.

Exemple : documentations d'une version libre et propriétaire d'un même logiciel

Vous avez réalisé la documentation d'un logiciel distribué sous licence propriétaire lorsqu'il est décidé de sortir une version open-source de ce produit. La version open-source présentant des différences avec la version propriétaire, il faut réaliser une documentation distincte.

Grâce à la définition de deux publics, l'un open-source, et l'autre non open-source, vous pouvez marquer les différentes parties uniquement destinées à chacun de ces deux publics :

• au niveau des maps des différents documents. Exemple :

  <backmatter>
    <notices href="fr_FR/topics/notices.dita">
      <topicref href="fr_FR/topics/cc-simple.dita" audience="ose"/>      
      <topicref href="fr_FR/topics/creative-commons.dita" audience="ose"/>
      <topicref href="fr_FR/topics/trademarks.dita"/>
    </notices>
  </backmatter>
  

• au niveau de chaque fichier de contenu DITA. Exemple :

      <step>
        <cmd audience="ose">
          Onglet
          <menucascade>
            <uicontrol conref="shared.dita#shared/system"/>
            <uicontrol conref="shared.dita#shared/routednetworks"/>
            <uicontrol conref="shared.dita#shared/add"/>
          </menucascade>
        </cmd>
        <choices audience="non-ose">
          <choice>
            <ph conref="shared.dita#shared/appliance"/>onglet
            <menucascade>
              <uicontrol conref="shared.dita#shared/system"/>
              <uicontrol conref="shared.dita#shared/routednetworks"/>
              <uicontrol conref="shared.dita#shared/add"/>
            </menucascade>
          </choice>
          <choice>
            <ph conref="shared.dita#shared/appliance"/>menu
            <menucascade>
              <uicontrol conref="shared.dita#shared/master-server"/>
              <uicontrol conref="shared.dita#shared/system"/>
              <uicontrol conref="shared.dita#shared/routednetworks"/>
              <uicontrol conref="shared.dita#shared/add"/>
            </menucascade>
          </choice>
        </choices>
      </step>
  

Il faut ensuite créer un fichier .ditaval par version. Exemple :

• ose.ditaval

    <?xml version="1.0" encoding="UTF-8"?>  
    <val>
      <prop att="audience" val="ose" action="include"/>
      <prop att="audience" val="non-ose" action="exclude"/>
    </val>
  

• non-ose.ditaval

    <?xml version="1.0" encoding="UTF-8"?> 
    <val>
      <prop att="audience" val="ose" action="exclude"/>
      <prop att="audience" val="non-ose" action="include"/>
    </val>
  

Lors de la génération des fichiers cibles avec DITA Open Toolkit, il suffit alors de passer le paramètre :

• /filter:ose.ditaval pour exclure les sections destinées uniquement à la version propriétaire, ou
• /filter:non-ose.ditaval pour exclure les sections destinées uniquement à la version open-source.

La valeur par défaut est include.

Un format adapté aux entreprises de toutes tailles

On lit parfois que DITA est plutôt réservée aux grandes entreprises et DocBook aux petites. La réutilisation du contenu étant aujourd'hui un enjeu stratégique pour toutes les entreprises, je pense au contraire que DITA est aussi bien adaptée aux TPE et PME qu'aux grands groupes. Pour avoir appris les deux formats tout seul, par la pratique, je peux témoigner que DITA n'est pas plus compliquée que DocBook.

DITA Open Toolkit

Le logiciel libre sous licence Apache 2.0 et Common Public License 1.0 DITA Open Toolkit transforme les maps et les topics DITA en livrables (PDF, RTF, HTML, Javahelp, etc.). Initialement développé par IBM, il est actuellement maintenu par une équipe de bénévoles. Il repose sur Java (personne n'est parfait), Ant, et XSL (XSLT/XPath/XSL-FO) et tourne sous GNU/Linux et Windows. Les développeurs peuvent créer des plugins pour effectuer de nouvelles transformations (telles que DocBook2DITA pour convertir du contenu Docbook en DITA) ou créer des spécialisations (telles que APIRef, spécialisation pour la documentation des logiciels).

Cas concret : documentation de NuFirewall

Pour la petite histoire, la documentation de NuFirewall, qui a été perçue par la presse comme un point fort du produit, a été réalisée sous DITA. Rien à voir avec cette architecture, me direz-vous ? Et pourtant si : si je n'avais pas utilisé un format qui favorise au maximum la réutilisation de l'information, je n'aurais pas autant pu me consacrer à l'essentiel : le contenu.

Bibliographie

• Introduction to DITA 2nd Edition
• The Dita Style Guide: Best Practices for Authors
• DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA
• Dita 101

Aller plus loin

• Rédacteur technique (399 clics)
• DITA Version 1.1 Language Specification (90 clics)
• Online Community for the Darwin Information Typing Architecture OASIS Standard (45 clics)