URL: https://linuxfr.org/news/reduire-les-couts-et-ameliorer-la-qualite-de-la-documentation-avec-dita-xml Title: Réduire les coûts et améliorer la qualité de la documentation avec DITA XML Authors: Gohar Benoît Sibaud et baud123 Date: 2012年03月20日T09:24:56+01:00 License: CC By-SA Tags: dita, docbook, génie_logiciel et documentation Score: 20 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](http://www.redaction-technique.org/redacteur-technique/dita-xml-open-toolkit-edition-creation-publication-open-source-logiciel-libre-linux/) 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. ---- [Rédacteur technique](http://www.redaction-technique.org/redacteur-technique/dita-xml-open-toolkit-edition-creation-publication-open-source-logiciel-libre-linux) [DITA Version 1.1 Language Specification](http://docs.oasis-open.org/dita/v1.1/CS01/langspec/ditaref-type.html) [Online Community for the Darwin Information Typing Architecture OASIS Standard](http://dita.xml.org) ---- # 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 : À 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 : Conref Système ## 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 : Cliquez sur Salut. Cliquez sur Bonjour. Information commune aux deux publics 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 : Cliquez sur Salut. Information commune aux deux publics Cliquez sur Bonjour. quitte à partager la section info par le mécanisme des _conref_ : Cliquez sur Salut. Cliquez sur Bonjour. 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 : * au niveau de chaque fichier de contenu DITA. Exemple : Onglet onglet menu Il faut ensuite créer un fichier _.ditaval_ par version. Exemple : * ose.ditaval * non-ose.ditaval 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](http://dita-ot.sourceforge.net/who_we_are.html). 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](http://linuxfr.org/news/nufirewall-le-pare-feu-libre-sans-prise-de-t%C3%AAte), qui a été perçue par la presse comme [un point fort du produit](http://www.linformaticien.com/tests/id/20068/categoryid/48/edenwall-nufirewall-le-pare-feu-nouvelle-generation.aspx), 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](http://comtech-serv.com//index.php?main_page=product_info&cPath=28_3&products_id=10) * [The Dita Style Guide: Best Practices for Authors](http://www.amazon.fr/Dita-Style-Guide-Practices-Authors/dp/0982811810/ref=sr_1_1?ie=UTF8&s=english-books&qid=1299761635&sr=8-1) * [DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA](http://www.amazon.fr/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522/ref=sr_1_4?s=english-books&ie=UTF8&qid=1332148376&sr=1-4) * [Dita 101](http://www.amazon.fr/Dita-101-Ann-Rockley/dp/0557072913/ref=sr_1_5?s=english-books&ie=UTF8&qid=1332148376&sr=1-5)

AltStyle によって変換されたページ (->オリジナル) /