Dossier Documentation modulaire 4/5

Troisième partie : Les standards de la documentation modulaire

La documentation modulaire s’appuie sur des standards qui permettent de gérer du contenu structuré. Sans être un expert de ces sujets techniques, il est bon de savoir un minimum de quoi il s’agit si on vous en parle dans le cadre d’un projet incluant la documentation modulaire. Voici donc une brève présentation des langages XML, DITA XML et Docbook.

3.1. Le langage XML

toucheXMLXML signifie eXtensible Markup Language, ce qui peut se traduire en français par Langage à balise étendu ou Langage à balise extensible.

Il s’agit d’un langage à balise (comme HTML) qui permet d’écrire des documents structurés et lisibles par un grand nombre d’applications.

Dans son glossaire, Pierre Attar présente le principe du langage XML de la façon suivante :

« Un document XML se compose, d’une part, de texte, et d’autre part, d’informations de structure. Les informations de structure servent à délimiter le texte pour en identifier la sémantique. Ainsi <metier>Consultant</metier> permet de dire que la chaîne de caractères « Consultant » doit être comprise comme étant une définition de métier.

Il est possible de délimiter des chaînes de caractères ; il est aussi possible de délimiter tout ensemble d’informations mélangeant texte et structure. Par exemple, dans le document suivant :

<metier>

<nom>

Consultant

</nom>

<descr>

Le consultant travaille pour des consultés qui…

</descr>

</metier>

La notion de métier introduit, d’une part, un nom de métier et d’autre part, une description de métier. C’est l’appartenance hiérarchique qui définit que tout cela parle bien du même métier : elle permet de spécialiser des descriptions : un nom de métier et une description de métier. »

XML permet donc d’écrire des documents structurés de façon arborescente et sémantique.

Les documents XML se réfèrent à des grammaires qui définissent comment un document XML doit être écrit pour être correct. Il s’agit des DTD (Definition Type Document).

Un document XML présente des données et leur structure, mais n’intègre pas d’information sur leur mise en forme (il est techniquement possible de le faire mais cela n’est pas recommandé pour des facilités de manipulation). Pour mettre en forme un document XML, on peut avoir recours à des feuilles de style, comme pour les documents HTML ou à XSLT (eXtensible Transformation Stylesheet Language) qui permet de formater des objets XML.

Les principaux avantages du format XML sont :

  • La lisibilité : le contenu d’un document XML est lisible et compréhensible directement par un être humain ;
  • Une structure arborescente permettant de modéliser de nombreux contenus ;
  • L’universalité et la portabilité : différents jeux de caractères sont pris en compte ;
  • La déployabilité : XML peut facilement être distribué par n’importe quel protocole à même de transporter du texte ;
  • L’intégrabilité : un document XML est utilisable par toute application pourvue d’un parser (c’est-à-dire un logiciel permettant d’analyser un code XML) ;
  • L’extensibilité : XML s’adapte au contexte dans lequel il est utilisé.

 3.2. DITA XML

DITA pour Darwin Information Typing Architecture peut se traduire en français par Architecture Darwinienne d’Information Typée. Il s’agit d’une norme basée sur XML permettant de rédiger des documents structurés et basée sur la réutilisation de contenu.

Avec DITA, la table des matières qui regroupe et organise tout le contenu du document est appelée map ou carte (plus précisément il s’agit d’un fichier .ditamap). Cette map contient les liens vers les différents éléments de contenu.

Avec DITA, ceux-ci sont appelés topic ou rubrique. Il existe quatre types de topic qui permettent de préciser la nature des informations qu’ils contiennent :

  • Topic concept qui décrit un objet, un concept. Il permet de répondre à la question « qu’est-ce que c’est ».
  • Topic task (tâche) qui contient une procédure, une méthode et permet de répondre à la question « comment faire ».
  • Topic reference (référence) qui contient des informations de référence.
  • Topic général duquel découlent les trois précédents.

A l’origine DITA est réservé à la documentation technique, ce qui explique cette spécialisation des topic.

Pour transformer les map DITA en document de différents formats, on utilise des spécifications DITA qui contiennent des règles de génération du contenu vers les formats de publication.

 3.3. Docbook

Docbook est un standard, basé sur XML, destiné à décrire des livres et des documents techniques.

Il est moins intéressant du point de vue de la documentation modulaire, car il n’est pas aussi axé réutilisation du contenu que DITA. Néanmoins, certains outils de documentation modulaire proposent le format Docbook. Il est aussi souvent comparé avec DITA, il est donc bien de le connaître afin de savoir lequel des deux est le plus approprié selon le contexte.

Docbook contient tous les éléments nécessaires pour décrire et structurer un contenu sous forme linéaire. Il est basé sur une DTD assez complexe qui peut être assez difficile à utiliser.

La publication et la mise en forme du document se font à l’aide de feuilles de style permettant de faire passer le document dans un autre format (PDF, HTML…).

2 réflexions sur “Dossier Documentation modulaire 4/5

  1. Pingback: Dossier Documentation modulaire 4/5 | D&IM ...

  2. Pingback: Dossier Documentation modulaire 4/5 | Bonnes pr...

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s