Darwin Information Typing Architecture

L'architecture Darwin Information Typing Architecture (DITA, littéralement Architecture Darwinienne et typage d'information) est une norme de rédaction modulaire et structurée dédiée au développement, à la conception, et à la publication de l'information technique. DITA est basé sur les technologies XML.

Le nom s'explique comme suit :

• Darwin : la norme inclut des principes d'héritage et de spécialisation et peut donc évoluer.
• Information typing (typage d'information) : la sémantique des types des rubriques (concepts, tâches, références) est liée à la structure de leur contenu (phrase, liste d'étapes, tableau). Chaque rubrique a également un objectif défini.
• Architecture : DITA est flexible et permet de réutiliser et développer différents types de livrables (architecture modulaire).

L'extensibilité de DITA permet aux organisations de définir des structures d'information spécifiques tout en continuant à utiliser une norme et un format ouvert (c'est-à-dire à la fois documenté, non-propriétaire et gratuit). La capacité à définir des architectures documentaires spécifiques pour une entreprise ou une industrie (voir les sous-comités du consortium OASIS) permet à DITA de réutiliser le contenu et de réduire les informations redondantes (en moyenne 50 %^{[réf. souhaitée]}).

Histoire

L'architecture DITA, sa DTD et son schéma XML ont été développés par IBM.

Le 1^er juin 2005, DITA devient une norme d'OASIS — consortium responsable des normes XML.

La version 1.2 de DITA a été adoptée le 1er décembre 2010.

La version 1.3 de DITA a été adoptée le 25 octobre 2016.

Parmi les entreprises soutenant le comité technique DITA, on trouve :

• IBM
• Cisco
• Département de la Défense des États-Unis
• Intel Corporation
• Oracle
• Microsoft

Les sous-comités d'OASIS peuvent travailler au développement d'une spécialisation pour une industrie particulière : machine industry, pharmaceutique, semi-conducteurs ou encore se penchent sur un usage ou un aspect spécifique (traduction, formation, aide, normes techniques).

Fonctionnalités

Réutilisation et modularité

DITA exploite le contenu sous forme de rubriques autonomes pouvant être exploitées dans plusieurs formats (Web, imprimable, mobile et applications embarquées), sur l'ensemble d'une gamme de produits, dans plusieurs types de document (guides, spécifications, formations, fiches produits...)

Chaque rubrique doit être suffisamment longue pour répondre aux besoins des publics cibles tout en étant suffisamment courte pour être facilement lue et réutilisée. Elle doit inclure suffisamment de contexte pour être comprise dans différents documents.

Les types de bases des rubriques : Task, Concept, Reference

La norme DITA inclut un nombre limité de rubriques « type » répondant à des objectifs spécifiques :

• Rubrique procédurale (task) : comprend la procédure à mener pour accomplir une tâche. La structure de la rubrique contient par exemple des prérequis, une série d'étapes que l'utilisateur doit suivre pour parvenir à son objectif. La rubrique doit répondre à la question de l'utilisateur "comment faire... ?".

• Rubrique concept (concept) : décrit un objet, un concept. La structure de la rubrique contient par exemple une description, une définition, des règles et des guides. La rubrique doit répondre à la question de l'utilisateur "qu'est-ce que c'est... ?".

• Rubrique référence (reference) : permet de rassembler des informations structurées et redondantes, non critiques pour les procédures. Par exemple, elle est utilisée pour lister des lignes de commandes, une liste de pièces détachées, une liste d'ingrédients, et tous types de matériau détaillé et factuel.

D'autres types de rubriques ont été ajoutés à ces trois types de base, notamment : reprise sur erreur (troubleshooting), entrée de glossaire (glossentry) et procédure machine (machinery task). Les informations de reprise sur erreur peuvent également être incluses dans les procédures.

Réutilisation du contenu

DITA encourage donc la rédaction du contenu sous forme de petites rubriques (topic) d'information, indépendantes (non contextualisées) et typées, à l'opposé des longs fichiers orientés livre/ouvrage.

Les rubriques elles-mêmes peuvent être réutilisées autant de fois que nécessaire dans une carte par le biais de liens (topic references). Les fragments d'information plus petits que les rubriques (un terme, un nom de marque, un avertissement de sécurité...) peuvent être également réutilisés dans l'ensemble d'une documentation (content references).

Il est également possible de créer des variables par le biais de référence indirectes nommées «clés». Ceci permet de résoudre des valeurs en fonction du contexte. En effet les valeurs sont fournies par les cartes. Ainsi, une même rubriques peut présenter une valeur différente selon la carte qui l'utilise.

Le texte conditionnel autorise la publication conditionnelle, c'est-à-dire le filtrage des informations dans les rubriques en fonction d'attributs types tels que : le public (expert, novice...), la plate-forme (Linux, Windows...), le produit, etc.

Les métadonnées étendues et personnalisables facilitent la recherche de sujets, leur catégorisation et le suivi des projets (états, mention de copyright, ligne de produit, etc.)

Mécanismes de spécialisation et généralisation

DITA peut être étendue et contrainte. Ainsi, il est possible d'ajouter de nouveaux éléments grâce à la spécialisation des éléments de base (c'est son côté Darwinien). Par le biais de la spécialisation, les architectes d'information ou les rédacteurs peuvent moduler et combiner de nouveaux module types et éléments types selon les besoins des compagnies et industries. Le mécanisme inverse de la spécialisation est appelé la généralisation.

Rubriques et spécialisations officielles

DITA inclut certaines spécialisations officielles dont DITA Learning and Training pour la création de contenus pédagogiques. Les rubriques et les cartes sont enrichies de métadonnées liées à la création de modules de cours, de programmes et d'un curriculum. Par exemple : connaissances requises, durée du module, etc. Certaines rubriques sont disponibles pour les contrôles de connaissance et l'introduction aux modules.

La norme contient également ces types de rubriques:

• Troubleshooting pour l'identification et la reprise sur erreur
• Machinery Task pour les interventions sur machines nécessitant des éléments sémantiques additionnels de type sécurité, liste des outils, temps estimé, etc.
• Glossentry et glossgroup pour la création des glossaires

Création du contenu

Créer du contenu avec DITA consiste à écrire des rubriques et des cartes. Une carte contient des liens vers les rubriques et définit le contour du document, en cela elle est en quelque sorte le reflet de la future table des matières. Elle définit le séquencement et la structure des rubriques, qui transparaîtront sur les livrables.

La carte permet au rédacteur de spécifier les sujets qui sont liés entre eux et de supprimer ou d'ajouter des liens et des séquences d'étapes.

Les fichiers DITA (cartes et rubriques) sont des fichiers XML. Chaque image, fichier vidéo, et tout autre fichier devant apparaître en sortie sont intégrés par un lien. N'importe quel éditeur XML (ou même texte) peut être utilisé pour écrire du contenu DITA. Il est toutefois plus facile d'utiliser un éditeur qui comprend et valide non seulement le XML, mais aussi la conformité à la norme DITA.

Traduction du contenu

DITA fournit un support pour la traduction avec l'attribut de localisation, par exemple @translate="no". Ceci indique si un élément ne doit pas être traduit. D'autres éléments incluent le sens de rédaction (droite-à-gauche ou gauche-à-droite), la langue, le filtrage de l'index et des termes qui doivent être inclus en publication.

Publication du contenu

DITA gère de bout en bout la production du contenu documentaire. En plus de préciser les éléments et les attributs qui font partie du langage DITA, les spécifications DITA incluent les règles d'impression du contenu, de génération HTML, d'aide en ligne, et d'exports vers d'autres formats. Par exemple, la spécification indique que si l'attribut «conref» de l'élément A contient une cible menant à l'élément B, le contenu de l'élément B sera affiché au sein de l'élément A. Les solutions de publications conformes à la norme DITA, ou au processeur DITA, supportent les attributs de réutilisations et résolvent le lien au moment de la publication. Des mécanismes existent également pour détailler et publier des textes conditionnels, des références vers des objets multimédia, des liens de rubriques à rubriques...

Lorsque DITA est devenue une norme OASIS, IBM a également reversé son processeur DITA à la communauté : le DITA Open Toolkit. Le DITA OT ne fait pas partie de la norme OASIS. Toutefois, cette boîte à outils open source permet de publier le contenu DITA vers différents formats de livrables print et Web grâce au langage Ant.

Parce que DITA est un format ouvert, de nombreuses extensions et plugins permettent au DITA OT de personnaliser les formats des exports, par exemple de publier vers EPUB, OOXML. Les types de fichiers valides supportés sont :

• PDF, par le biais de XSL-FO et XSLT,
• XHTML,
• Microsoft Compressed HTML,
• Aide Eclipse,
• Aide Java,
• Aide Oracle,
• RTF (Rich Text Format).

La plupart des utilisateurs DITA démarrent leur projet avec le DITA Open Toolkit et les outils de publication sont intégrés au processus de documentation de nombreuses entreprises.

Le DITA Open Toolkit est un projet open source très actif soutenu par plusieurs grandes sociétés qui contribuent directement à son développement (IBM, Adobe Systems, OASIS, etc.). Téléchargement disponible sur GitHub.

Compatibilité avec d'autres normes

DITA est compatible avec les normes suivantes :

• ISO/CEI/IEEE 82079 - découpage en procédures, concept et références
• Avertissement de sécurité ANSI Z535 and ISO 3864-2 (depuis la version 1.2)
• Code ISO 639 de définition des langues
• Standard Technical English pour la séparation des informations conceptuelles et d'instructions

Exemples de rubriques

Exemple de fichier ditamap type linéaire (structure de table des matières)

  <?xml version="1.0" encoding="utf-8"?>
  <!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "../dtd/bookmap/dtd/bookmap.dtd">
  <bookmap id="taskbook">
    <booktitle>
      <mainbooktitle>Exemple de structure de table des matières</mainbooktitle>
    </booktitle>
    <chapter href="topics/introduction.dita">
      <topicref href="tasks/procedure.dita"/>
    </chapter>
  </bookmap>

Exemple de texte général (DTD topic)

  
    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA 1.2 Topic//EN" "../../dtd/technicalContent/dtd/topic.dtd">
    <topic id="exemple-topic" xml:lang="fr-fr">
      <title>Exemple de section topic</title>
      <body>
        <hazardstatement>
          <!-- la valeur audience permet de créer du texte conditionnel ; plusieurs versions différentes peuvent être publiées via l'utilisation d'un fichier .ditaval -->
          <messagepanel audience="electriciens">
            <typeofhazard>
              Danger électrique
            </typeofhazard>
            <consequence>
              Risque d'électrocution
            </consequence>
            <howtoavoid>
              Ne touchez pas les fils électriques.
            </howtoavoid>
          </messagepanel>
          <messagepanel audience="plombiers">
            <typeofhazard>
              Dégâts des eaux
            </typeofhazard>
            <consequence>
              Risque de noyade
            </consequence>
            <howtoavoid>
              Ne plongez pas dans la piscine.
            </howtoavoid>
          </messagepanel>
        </hazardstatement>        
        <p>
          Paragraphe.
        </p>
        <example>
          <title>
            Exemple
          </title>      
          <p>
            Un exemple.
          </p>
          <note type="important">
            Remarque importante.
          </note>
          <fig>
            <title>Illustration</title>        
            <image href="../images/schemas/illustration.png" placement="break"
                   align="center"><alt>Texte descriptif de l'image</alt></image>
          </fig>
        </example>
      </body>
    </topic>
  

Exemple de procédure (DTD task)

  
    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "../../dtd/technicalContent/dtd/task.dtd">
    <task id="sample" xml:lang="fr-fr">
      <title>Exemple de procédure pas à pas</title>
      <shortdesc>Ceci est un exemple de procédure pas à pas.</shortdesc>
      <!-- Ceci est un commentaire -->
      <taskbody>
        <context>
          <p>
            Cette partie indique le contexte dans lequel se déroule la procédure.
          </p>
        </context>
        <steps>
          <stepsection>Pour effectuer la procédure :</stepsection>
          <step>
            <cmd>
              Cliquez sur <uicontrol>l'option 1</uicontrol>.
            </cmd>
            <stepxmp>
              Exemple pour cette étape.
            </stepxmp>
          </step>
          <step>
            <cmd>
              Cliquez sur <uicontrol>l'option 2</uicontrol>.
            </cmd>
            <info>
              Toute information supplémentaire.
            </info>
            <substeps>
              <substep>
                <cmd>
                  Effectuez cette étape secondaire.
                </cmd>
              </substep>
              <substep>
                <cmd>
                  Effectuez cette étape secondaire.
                </cmd>
              </substep>
            </substeps>
            <choices>
              <choice>
                Choix 1
              </choice>
              <choice>
                Choix 2
              </choice>
            </choices>
          </step>
          <step>
            <cmd>
              Cliquez sur <uicontrol>l'option 3</uicontrol>.
            </cmd>
            <stepresult>
              Voici le résultat de la procédure.
            </stepresult>
          </step>
        </steps>
      </taskbody>
      <!-- section "Voir aussi" -->
      <related-links>
        <link href="../concepts/introduction.dita" format="dita" type="concept"></link>
      </related-links>
    </task>
  

Exemple de fichier .ditaval (pour filtrer le texte conditionnel)

  
    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE val PUBLIC "-//OASIS//DTD DITA DITAVAL//EN" "ditaval.dtd">
    <val>
      <prop att="audience" val="electriciens" action="exclude"/>
      <prop att="audience" val="plombiers" action="include"/>
    </val>
  

Notes et références

(en)/(es) Cet article est partiellement ou en totalité issu des articles intitulés en anglais « Darwin Information Typing Architecture » (voir la liste des auteurs) et en espagnol « DITA » (voir la liste des auteurs).

Articles connexes

• DocBook
• TEI

Liens externes

• Introduction à la norme DITA - Source IBM (en)
• Une autre introduction (en français)
• DITA Version 1.3 OASIS specifications
• DITA et TIM (Task-oriented Information Modelling)
• Patrick Peccatte (2009) Les concepts fondamentaux de DITA
• Data Conversion Laboratory (2008) DocBook and DITA - en anglais
• DITA XML pour le rédacteur technique : créer et publier des documents DITA XML avec des logiciels libres (didacticiels en français)
• Le Guide de style DITA - Bonne pratiques pour les rédacteurs
• Learning DITA (en cours de traduction vers le français)