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[1]. 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][2],[3]).

Histoire

modifier

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

Le 1er juin 2005, DITA devient une norme d'OASIS[4] — 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 :

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

modifier

Réutilisation et modularité

modifier

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

modifier

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) et entrée de glossaire (glossentry), procédure machine (machinery task). Les informations de reprise sur erreur peuvent également être incluses dans les procédures.

Réutilisation du contenu

modifier

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

modifier

DITA peut être étendue et contrainte - ainsi il est possible d'ajouter de nouveaux éléments, à travers 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 donc 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

modifier

DITA inclut certaines spécialisations officielles dont DITA Learning and Training[5] pour la création de contenus pédagogiques. Les rubriques et cartes sont notamment enrichies de métadonnées liées à la création de modules de cours, programmes et 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

modifier

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 transparaitront sur les livrables.

La carte permet au rédacteur de spécifier quels sujets 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

modifier

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

modifier

DITA gère de bout en bout la production du contenu documentaire. En plus de préciser quels éléments, attributs 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 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 :

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

modifier

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

modifier

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

modifier

  <?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)

modifier
  
    <?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)

modifier
  
    <?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)

modifier
  
    <?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

modifier
(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).
  1. Tony Self, « Introduction à DITA », sur www.ixiasoft.com (consulté le )
  2. (en) « Harmonizer | Data Conversion Laboratory », sur DCL (consulté le )
  3. (en-US) ditawriter, « The Four Stages of Cost Savings to Expect when Moving to an XML-based Documentation Process », sur DITA Writer, (consulté le )
  4. « OASIS Darwin Information Typing Architecture (DITA) TC » (consulté le ).
  5. « DITA Learning and Training Content Specialization SC | OASIS », sur www.oasis-open.org (consulté le )

Articles connexes

modifier

Liens externes

modifier