Cas concret : documentation de NuFirewall
La documentation NuFirewall, saluée par la presse comme un atout produit, a été réalisée en DITA XML - étude de cas en authoring structuré pour logiciel informatique.
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 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 →.
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.
Les pratiques qui ont permis cette réutilisation, en un coup d’œil :
- Centraliser les conref dans un fichier unique. Il est beaucoup plus facile de placer tous les éléments sources dans 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 que de les chercher dans une multitude de fichiers.
- Utiliser le nœud XML de plus bas niveau. Le nœud DITA XML de plus bas niveau contenant l’information à partager sert de source au 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 →.
- Prendre en compte les contraintes de traduction. N’appliquer le mécanisme conref qu’à une phrase complète ou à un terme qui ne sera jamais traduit.
- Limiter l’imbrication des conref. Au-delà d’un seul niveau d’imbrication, le contenu peut vite devenir ingérable.
- Maximiser l’utilisation des conref pour faire baisser les coûts. Les conref font baisser les coûts et les délais de publication, surtout pour les documents multilingues.
- Protéger les informations confidentielles. Le contenu confidentiel, placé dans un fichier à part, n’est jamais traduit ni livré dans la langue cible.
- Fournir une information ciblée avec le texte conditionnel ditaval. Inclure ou exclure des blocs marqués à la compilation, sans créer deux fichiers pour des variations mineures.
Partager des blocs d’information atomiques avec les conref
Section intitulée « 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 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 →, 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
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 (XML Schema Definition)Le langage de schéma XML du W3C, lui-même écrit en XML. Les schémas XSD de DITA XML définissent les éléments autorisés dans chaque type de topic ; un fichier qui ne les respecte pas échoue à la validation, ce qui limite aussi ce que les conrefs et le texte conditionnel peuvent produire.Voir dans le glossaire → 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
Centraliser les conref dans un fichier unique
Section intitulée « 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 (réutilisation de contenu)Rédiger une information une seule fois et l'employer à plusieurs endroits ou dans plusieurs livrables plutôt que de la recopier : une correction faite une fois s'applique partout. Les conrefs, le texte conditionnel et le single-sourcing sont autant de moyens d'y parvenir.Voir dans le glossaire → 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
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 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 → 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
Section intitulée « 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
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></task>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>) contient d’autres nœuds que <step> (par exemple <info>).
Placement du conref sur le nœud XML de plus haut niveau
Dans le 2e cas, tout le contenu du nœud <step> 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
Section intitulée « 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, qui est incorrecte : en français, l’adjectif bleue doit se placer après le nom flèche. La phrase correcte, Cliquez sur la flèche bleue, exigerait que les segments soient assemblés dans un ordre différent pour cette langue.
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.)
Limiter l’imbrication des conref
Section intitulée « Limiter l’imbrication des 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 !
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
Section intitulée « 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.
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 proprement dit - et non le balisage qui l’entoure - 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
Section intitulée « 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 DitavalUn fichier de filtre DITA XML qui inclut ou exclut du contenu marqué avec des attributs correspondants au moment de la compilation — le mécanisme derrière le texte conditionnel de DITA.Voir dans le glossaire → 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-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 → 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
Section intitulée « 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 conditionnelContenu marqué comme ne s'appliquant qu'à un public, une version de produit ou un livrable donnés, afin qu'une même source puisse être filtrée à la compilation pour produire des documents différents. DITA XML le met en œuvre avec les fichiers ditaval ; des moteurs de modèles comme Jinja font de même pour les formats texte.Voir dans le glossaire → 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.
Grâ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.