# Cas concret : documentation de NuFirewall ## Aperçu 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. Les pratiques qui ont permis cette réutilisation, en un coup d’œil : - **[Centraliser les conref dans un fichier unique](#centraliser-les-conref-dans-un-fichier-unique).** Il est beaucoup plus facile de placer tous les éléments sources dans un référentiel unique que de les chercher dans une multitude de fichiers. - **[Utiliser le nœud XML de plus bas niveau](#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 conref. - **[Prendre en compte les contraintes de traduction](#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](#limiter-limbrication-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](#maximiser-lutilisation-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](#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](#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 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. > **Schéma: Partage de blocs d'information entre ditamap** > > Schéma montrant le ditamap A référençant 1.dita et 2.dita, et le ditamap B référençant 2.dita et 3.dita, avec 2.dita partagé entre les deux ditamaps. **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. > **Schéma: Partage de blocs d'information fins avec les conref** > > Schéma montrant shared.dita comme source du conref, référencé par dita-1.dita et dita-2.dita comme cibles du conref. **Partage de blocs d'information de granulométrie fine entre les sections DITA XML** ### Centraliser les conref dans un fichier unique > **Note** > > Pour favoriser l'utilisation des conref au sein d'une équipe de rédacteurs techniques, et également pour simplifier la maintenance des conref, il s'avère très efficace de centraliser tous les conref dans un fichier DITA XML dédié. 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. > **Schéma: Gestion décentralisée des conref** > > Schéma montrant trois fichiers DITA se référençant les uns les autres en cercle, sans fichier source central. **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). > **Schéma: Bonne gestion des conref** > > Schéma montrant shared.dita comme source du conref, référencé par dita-1.dita et dita-2.dita comme cibles du conref. **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. > **Schéma: Conref sur le nœud XML de plus bas niveau** > > Schéma montrant un conref placé sur un nœud cmd de bas niveau, référençant un autre nœud cmd. **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 : ```xml Cliquez sur OK. ``` Pour être conforme au schéma XSD, votre code doit au moins être structuré comme suit : ```xml Conref source Cliquez sur OK. ``` 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 : ```xml Cliquez sur OK. ``` plutôt que la suivante : ```xml Cliquez sur OK. ``` En effet, dans le premier cas, vous pourrez utiliser le *conref* même si le nœud supérieur (``) contient d'autres nœuds que `` (par exemple ``). > **Schéma: Conref sur le nœud XML de plus haut niveau** > > Schéma montrant un conref placé sur un nœud step de haut niveau, référençant un autre nœud step et remplaçant tout son contenu. **Placement du *conref* sur le nœud XML de plus haut niveau** Dans le 2e cas, tout le contenu du nœud `` sera remplacé par la valeur du *conref* source. Par exemple, dans le cas suivant, tout le contenu du nœud sera absent des livrables : ```xml Si vous ne savez pas lire, c'est le bouton vert. ``` ### Prendre en compte les contraintes de traduction L'unité d'information DITA XML la plus petite est le nœud ``. 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](https://docs.redaction-technique.org/fr/tech-writing-process/translation/). > **Schéma: Les phrases se découpent différemment selon les langues** > > Schéma montrant les mêmes segments conref assemblés dans un ordre différent pour deux langues, illustrant pourquoi le conref au niveau du segment ne se traduit pas proprement. **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 : ```xml Click the blue arrow ``` Vous pouvez maintenant utiliser le code suivant : ```xml

.

``` 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 : ```xml Cliquez sur la bleue flèche ``` 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 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** ```xml

Pour de plus amples informations, voir le .

``` 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 ! > **Schéma: Imbriquer les conref sur plusieurs niveaux est risqué** > > Schéma montrant trois niveaux d'imbrication de conref, un conref pointant vers un conref pointant vers un autre conref. **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 > **Astuce** > > Recourir aux conref est le meilleur moyen dont dispose le rédacteur technique pour faire baisser spectaculairement les coûts et les délais de publication de son contenu DITA XML, surtout pour les documents multilingues. 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*. > **Schéma: 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 Afficher les tendances
``` 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. > **Note** > > Ne croyez pas qu'il s'agit là d'une contrainte spécifiquement induite par la modularisation poussée du contenu. Pour avoir fait une école de traduction reposant sur le principe simple mais efficace du *triangle du sens* (le traducteur doit comprendre le texte source pour le reformuler dans le texte cible et non transcrire une suite de mots d'une langue à l'autre) et avoir pratiqué la traduction technique durant plusieurs années, je sais que tout projet de traduction réussi repose sur une collaboration efficace entre concepteurs, rédacteurs et traducteurs. 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 > **Astuce** > > Le puissant mécanisme conref de DITA XML se prête à d'autres applications que la réduction des coûts. Par exemple, le rédacteur technique peut masquer des informations dans le code source. 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 ! > **Schéma: Masquer des informations confidentielles aux traducteurs** > > Schéma montrant une source confidentielle en langue A divisée par la traduction en deux branches, chacune filtrée par ditaval, produisant un livrable langue A conservant les informations confidentielles et un livrable langue B les excluant. **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. > **Schéma: Texte conditionnel avec ditaval** > > Schéma montrant une source filtrée par ditaval vers deux cibles distinctes, chacune ne recevant que le contenu qui lui est destiné. **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. 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 : ```xml Ramenez l'intensité sous la dose létale de 150mA. ``` > **Attention** > > Une clé de filtrage mal positionnée peut entraîner une erreur de compilation. En effet, si le code non filtré est conforme au schéma XSD DITA XML, le code filtré peut ne pas l’être. **Exemple** Le code suivant est correct avant filtrage : ```xml Commande Description ``` Après filtrage, en revanche, on obtient le code suivant : ```xml ``` Or, selon le schéma XSD, les en-têtes de tableaux doivent contenir au moins une ligne : ```xml ``` Ce code est donc incorrect et entraîne l’échec de la compilation. ## Articles connexes - [Cas concrets d’utilisation de DITA XML](https://docs.redaction-technique.org/fr/formats/dita-xml-case-studies/) - [Du document à la base documentaire modulaire](https://docs.redaction-technique.org/fr/formats/modular-documentation/) - [Une architecture documentaire trop complexe ?](https://docs.redaction-technique.org/fr/formats/document-architecture-complexity/) - [Didacticiels DITA XML et XSL-FO](https://docs.redaction-technique.org/fr/tutorials/dita-xml-xsl-fo-tutorials/) --- Source: https://docs.redaction-technique.org/fr/formats/nufirewall-case-study/