Cas concret : documentation de NuFirewall

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 XML.

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.

Partager des blocs d’information atomiques avec les conref

Lorsque le rédacteur technique veut réutiliser des blocs d’information DITA XML plus petits qu’une section, il doit les partager au niveau des fichiers de contenu dita et non dans les structures de table des matières ditamap, grâce au mécanisme conref.

Le principe des conref est simple : lorsqu’un conref est mentionné au niveau d’un nœud XML donné, tout le contenu du nœud cible est remplacé par le contenu du nœud source.

Partage de blocs d'information de granulométrie large entre les ditamap Partage de blocs d’information de granulométrie large entre les ditamap

Une différence notable entre le mécanisme des conref et le mécanisme XML des xinclude, c’est que le nœud source doit être conforme au schéma XSD du fichier source et du fichier cible. Ce formalisme rigoureux, s’il s’avère moins souple et oblige parfois à quelques acrobaties, rend les conref beaucoup plus lisibles que les xinclude et favorise leur utilisation.

Partage de blocs d'information de granulométrie fine entre les sections DITA XML Partage de blocs d’information de granulométrie fine entre les sections DITA XML

Centraliser les conref dans un fichier unique

Il est a priori plus simple, pour réutiliser un contenu d’un fichier DITA XML existant, de pointer vers ce contenu sans l’extraire de son contexte d’origine. Cependant, un des grands principes de la réutilisation du contenu est de décontextualiser le contenu. Il est donc à terme beaucoup plus efficace pour le rédacteur technique d’extraire le contenu réutilisé de son fichier d’origine et de le placer dans un fichier ne contenant que des sources de conref. Il est en effet beaucoup plus facile de placer tous les éléments sources dans un référentiel unique que de devoir chercher les différentes sources dans une multitude de fichiers.

Gérer les conref de manière décentralisée est peu efficace Gérer les conref de manière décentralisée est peu efficace.

Les conref sont en effet résolus à la compilation même si les fichiers contenant les valeurs sources ne sont pas référencés dans le fichier ditamap permettant de générer le livrable (ce qui veut dire également que les fichiers contenant les valeurs sources des conref peuvent se trouver dans un répertoire de niveau supérieur à celui du ditamap).

Bonne gestion des conref

Les fichiers de contenu référencés dans des structures ditamap ne contiennent donc que des conref cibles, et un fichier central fédère tous les conref sources ; il contient éventuellement également quelques références internes à des conref cibles.

Ce fichier central doit être de même type (task, concept, reference, etc.) que les fichiers de contenu, ou du moins du type composite, qui accepte tous types de structures DITA XML. Pour des raisons d’organisation, je trouve personnellement efficace de créer un fichier central par type de topic DITA XML, et donc de même type, pour partager les informations propres à chaque type. Je réserve le type composite à un fichier central fourre-tout contenant des informations partagées entre différents types de topics.

Tous les conref sources d’un fichier donné doivent avoir un ID unique dans ce fichier ; veillez à utiliser des noms explicites pour les humains, vos fichiers dita contenant des conref cibles deviendront sinon rapidement illisibles !

Utiliser le nœud XML de plus bas niveau

Le rédacteur technique doit utiliser comme source du conref le nœud DITA XML de plus bas niveau contenant l’information à partager.

Le but des conref étant de gérer des blocs d’information de faibles dimensions, il est logique de les manipuler au niveau de la plus petite structure XML encapsulant l’information, même si cette structure, pour être compatible avec le schéma XSD de la section DITA XML où elle intervient, doit elle-même être incluse dans des structures XML plus grandes.

Placement du conref sur le nœud XML de plus bas niveau Placement du conref sur le nœud XML de plus bas niveau.

Vous voulez par exemple réutiliser la phrase Cliquez sur OK. Vous ne pouvez cependant pas indiquer dans le fichier contenant les conref sources uniquement le code suivant :

<cmd>Cliquez sur OK.</cmd>

Pour être conforme au schéma XSD, votre code doit au moins être structuré comme suit :

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA 1.2 Task//EN"
/usr/share/dita-ot/dtd/technicalContent/dtd/task.dtd">
<task id="shared" xml:lang="fr-fr">
  <title>Conref source</title>
  <taskbody>
    <steps>
      <step>
        <cmd>
          Cliquez sur OK.
        </cmd>
      </step>
    </steps>
  </taskbody>

Il s’agit maintenant de placer un ID sur une structure XML afin de pouvoir réutiliser le contenu de cette structure. En l’occurrence, c’est une étape unique comprenant une commande unique que vous souhaitez réutiliser.

Il est alors préférable d’utiliser la syntaxe suivante :

<step>
  <cmd id="click-ok">
    Cliquez sur OK.
  </cmd>
</step>

plutôt que la suivante :

<step id="click-ok">
  <cmd>
    Cliquez sur OK.
  </cmd>
</step>

En effet, dans le premier cas, vous pourrez utiliser le conref même si le nœud supérieur (<step>{.interpreted-text role=“samp”}) contient d’autres nœuds que <step>{.interpreted-text role=“samp”} (par exemple <info>{.interpreted-text role=“samp”}).

Placement du conref sur le nœud XML de plus haut niveau Placement du conref sur le nœud XML de plus haut niveau.

Dans le 2e cas, tout le contenu du nœud <step>{.interpreted-text role=“samp”} sera remplacé par la valeur du conref source. Par exemple, dans le cas suivant, tout le contenu du nœud sera absent des livrables :

<step id="click-ok">
  <cmd/>
  <info>
    Si vous ne savez pas lire, c'est le bouton vert.
  </info>
</step>

Prendre en compte les contraintes de traduction

L’unité d’information DITA XML la plus petite est le nœud <ph>. Le rédacteur technique doit cependant veiller à ne lui appliquer le mécanisme conref que pour une phrase complète ou un terme qui ne sera jamais traduit (par exemple, le nom de la société ou d’un produit). De gros problèmes apparaissent sinon lors de la traduction dans d’autres langues.

Les phrases se découpent différemment selon les langues.

Exemple

Si vous décidez de pousser la granulométrie au niveau du segment de phrase et que vous définissez les conref suivants :

<ph id="click">Click the</ph>

<ph id="blue">blue</ph>

<ph id="arrow">arrow</ph>

Vous pouvez maintenant utiliser le code suivant :

<p>
  <ph conref="shared.dita/click"/>
  <ph conref="shared.dita/blue"/>
  <ph conref="shared.dita/arrow"/>.
</p>

pour que soit générée la phrase Click the blue arrow.

Essayons maintenant de créer une version française de cette phrase. Nous traduisons donc les conref comme suit :

<ph id="click">Cliquez sur la</ph>

<ph id="blue">bleue</ph>

<ph id="arrow">flèche</ph>

Nous obtenons alors la phrase Cliquez sur la bleue flèche.

Pour pallier ce problème, il faudrait réorganiser l’ordre des conref dans le fichier DITA XML traduit, ce qui est difficilement gérable et fait perdre tout l’intérêt du mécanisme. Sans compter que des problèmes pires que ce cas d’école peuvent conduire à complètement abandonner dans la langue cible les conref utilisés dans la langue source (je n’ai pas d’exemple concret à offrir, ayant toujours évité de tomber dans ce genre de travers.)

Imbriquer les conref

Pour des raisons de facilité de mise à jour et de maintenance du contenu DITA XML, le rédacteur technique doit limiter l’effet poupée russe et ne pas trop imbriquer les conref. Un seul niveau d’imbrication (un conref imbriqué dans un autre) me semble le seuil au-delà duquel le contenu peut vite devenir ingérable.

Dans l’exemple ci-dessous, le conref source see-admin-guide contient le conref cible admin-guide-title :

Exemple

<p id="see-admin-guide">
  Pour de plus amples informations, voir le <ph
  conref="shared.dita/admin-guide-title"/>.
</p>

Ce niveau de complexité est gérable. Mais si le conref source admin-guide-title contient lui même un conref cible, le code DITA XML devient un vrai plat de spaghettis (sans compter les risques de référence circulaire). Les conref peuvent théoriquement être combinés à l’infini, mais les problèmes pratiques que cela engendre peuvent également être infinis !

Imbriquer les conref sur plusieurs niveaux : puissant, mais dangereux ! Imbriquer les conref sur plusieurs niveaux : puissant, mais dangereux !

Pour résumer la situation :

Il est tout à fait possible d’imbriquer plusieurs conref sources. Le seul effet de bord négatif porte sur la lisibilité du fichier contenant les conref.
L’imbrication de conref sources et cibles est possible mais rapidement ingérable.
Il est impossible d’imbriquer des conref cibles : le contenu du conref du niveau supérieur écrasera les valeurs des conref du niveau inférieur.

Maximiser l’utilisation des conref pour faire baisser les coûts

De par la nature des informations qu’elles contiennent, les sections de type task ont un taux plus élevé de réutilisation du contenu que celles de type concept ou reference.

Les conref modularisent de petits blocs d'information Les conref modularisent de petits blocs d’information.

Comme dans l’exemple ci-dessous, il n’est pas rare d’obtenir rapidement des fichiers dont la seule valeur unique est le titre, le reste du contenu, pourtant unique (car il assemble de manière unique des blocs d’information non uniques), étant généré par des conref.

Exemple

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA 1.2 Task//EN"
"/usr/share/dita-ot/dtd/technicalContent/dtd/task.dtd">
<task id="display-trends" xml:lang="fr-fr">
  <title>Afficher les tendances</title>
  <taskbody>
    <context audience="basic">
      <note type="restriction" audience="advanced">
        <ul>
          <li>
            <ph conref="shared.dita/ip-control"/>
          </li>
        </ul>
        <ph conref="../../shared/shared.dita/see-user-guide"
        audience="no-user-guide"/>
      </note>
    </context>
    <steps>
      <step>
        <cmd audience="basic">
          <menucascade>
            <uicontrol conref="shared.dita/logs"/>
          </menucascade>
        </cmd>
        <choices audience="advanced">
          <choice>
            <ph conref="shared.dita/physical-appliance"/>
            <menucascade>
              <uicontrol conref="shared.dita/logs"/>
            </menucascade>
          </choice>
          <choice>
            <ph conref="shared.dita/virtual-appliance"/>
            <menucascade>
              <uicontrol conref="shared.dita/server"/>
              <uicontrol conref="shared.dita/logs"/>
            </menucascade>
          </choice>
        </choices>
      </step>
      <step>
        <cmd>
          <menucascade>
            <uicontrol conref="shared.dita/all"/>
            <uicontrol conref="shared.dita/editfile"/>
          </menucascade>
        </cmd>
        <info>
          <ul conref="shared.dita/drill-down">
            <li/>
          </ul>
          <note conref="shared.dita/randomnames"/>
        </info>
      </step>
    </steps>
  </taskbody>
</task>

Seul le texte en noir doit être traduit. Traduire ce type de fichier de contenu DITA XML consiste donc à traduire uniquement le titre de la section et l’intégralité des conref sources. Lorsqu’il traduit un ensemble d’unités d’information placées en vrac dans un fichier, le traducteur manque cependant cruellement de contexte. Le créateur du contenu initial doit donc lui fournir une assistance constante. La méthode la plus efficace consiste à faire travailler le traducteur en régie. Avantage supplémentaire : il pourra ainsi interroger non seulement le rédacteur technique, mais également les concepteurs du produit.

Il est également possible de factoriser ainsi des éléments de structure, et non de contenu, tels que des en-têtes de tableaux. Vous pouvez ainsi présenter des informations de même type de manière homogène à moindre coût, c’est à dire sans recourir à la spécialisation.

Protéger les informations confidentielles

Voici un cas original d’utilisation des conref : imaginez que vous devez faire traduire un fichier contenant des informations confidentielles qui ne doivent pas figurer dans la version traduite et auxquelles le traducteur ne doit pas avoir accès (une clause de confidentialité interdit aux clients de diffuser l’information dont ils disposent).

Comment faire ? Le filtrage à l’aide du mécanisme ditaval est conçu pour exclure des informations des livrables, non pour les masquer dans les fichiers sources. Allez-vous devoir créer deux jeux de fichiers sources, certains comportant les informations confidentielles, les autres non ? Adieu alors le single-sourcing et la réutilisation du contenu qui vous ont fait choisir DITA XML !

Masquer des informations confidentielles aux traducteurs

En plaçant le contenu confidentiel dans un fichier que vous appelez par exemple confidentiel.dita et en plaçant des conref assortis d’une clé de filtrage dans le fichier à traduire, vous avez résolu votre problème : le traducteur ne traduira que le texte non confidentiel, et le livrable généré dans la langue cible ne contiendra pas le texte confidentiel, noté comme conditionnel et exclu explicitement par le fichier ditaval passé en argument lors de la compilation.

Fournir une information ciblée avec le texte conditionnel ditaval

Un fichier ditaval reprend le principe des lunettes que vous chaussez pour visualiser un film en 3D : le verre gauche masque une moitié de l’image, le verre droit en masque l’autre moitié. Mais seul le rédacteur technique dispose de lunettes 3D et a une vision complète de l’information contenue dans le projet DITA XML.

Les destinataires de l’information disposent de lunettes avec deux verres gauches ou deux verres droits. Ils ne voient donc qu’une partie de l’information. Loin d’être lésés par cet état de fait, ils ont ainsi un meilleur accès à l’information. Le profilage réalisé masque à chaque public les informations dont ils n’ont pas besoin et qui ne seraient pour eux que du bruit. Chaque audience bénéficie donc d’un meilleur accès à l’information qui la concerne, selon le fameux concept minimaliste de less is more.

Texte conditionnel avec DITA XML

Concrètement, le mécanisme ditaval est basé sur des opérateurs binaires : vous marquez un bloc d’information avec un attribut et une valeur, puis incluez ou excluez ce bloc dans le livrable en passant un opérande lors de la compilation (le bloc est inclus par défaut si aucun opérande n’est spécifié). C’est le principe du texte conditionnel.

Gâce à ce mécanisme, il n’est pas nécessaire de créer deux fichiers différents lorsque leur contenu ne comporte que des variations mineures. C’est un outil de plus destiné à réduire la redondance du contenu source.

Vous pouvez appliquer des clés de filtrage en série (condition et) en indiquant plusieurs valeurs séparées par des espaces dans les attributs product, audience ou autre.

Exemple

Pour indiquer qu’une remarque est destinée à la fois à des électriciens et à des utilisateurs avancés en voulant profiler l’information selon les publics suivants :

non électriciens,
électriciens débutants,
électriciens experts.

Vous pouvez utiliser la structure suivante :

<step audience="electricians advanced">
  <cmd> Ramenez l'intensité sous la dose létale de 150mA. </cmd>
</step>

Exemple

Le code suivant est correct avant filtrage :

<thead>
  <row product="a>
    <entry>Commande</entry>
    <entry>Description</entry>
  </row>
</thead>

Après filtrage, en revanche, on obtient le code suivant :

<thead>
</thead>

Or, selon le schéma XSD, les en-têtes de tableaux doivent contenir au moins une ligne :

<!ENTITY % thead.content "((%row;)+)>

Ce code est donc incorrect et entraîne l’échec de la compilation.