L’approche d’écriture que nous conseillons est basée sur l’utilisation de la norme DITA comme un modèle d’information.

DITA [Darwin information typing architecture]

DITA comprend trois types de sujet spécialisé: Tâche, Concept et Référence. Chacun de ces trois types de sujet est une spécialisation d’un type de thème générique, qui contient un élément de titre, un élément prologue pour les métadonnées, et un élément de corps. L’élément de corps contient paragraphe, le tableau, et les éléments de la liste, semblable à HTML. Un sujet tâche (général) est destiné à une procédure qui décrit comment accomplir une tâche. Un sujet tâche répertorie une série d’étapes que les utilisateurs suivent pour produire un résultat escompté. Les étapes sont contenues dans un élément « taskbody », qui est une spécialisation de l’élément de corps générique. L’élément étapes est une spécialisation d’un élément de liste ordonnée. Concept est plus objectif, contenant des définitions, les règles et lignes directrices. Référence est pour les rubriques qui décrivent la syntaxe de commande, des instructions de programmation, et d’autres documents de référence, et contient généralement des matières détaillée et factuelle.

Ça c’est DITA.

Allons plus loin avec DITA, pour surclasser les « topics » DITA afin d’aider les auteurs à comprendre comment catégoriser l’information.

Selon DITA, c’est de la spécialisation pour des secteurs industriels:

La spécialisation DITA

DITA permet d’ajouter de nouveaux éléments et attributs à travers la spécialisation des éléments et attributs de base. Avec la spécialisation, DITA peut accueillir de nouveaux types de topics, d’éléments et d’attributs, pour satisfaire les besoins d’entreprises ou d’industries en particulier. La flexibilité de DITA permet aux organisations de spécialiser le modèle d’information en définissant des structures d’informations spécifiques et en continuant d’utiliser des outils standards pour les utiliser. La faculté de définir des architectures d’information spécifiques en fonction des entreprises leur permet d’utiliser DITA pour enrichir le contenu avec des métadonnées ayant un sens métier, et aussi pour appliquer les règles de l’entreprise en matière de structure documentaire.

C’est très bien tout cela, la spécialisation est ce que nous proposons. Mais comment la transformer en une méthodologie pratique ?

La typologie que nous définissons aide les rédacteurs à savoir ce qu’ils doivent écrire, à trouver l’information, à la réutiliser facilement, mais également à rester pertinent.

Nous appelons les éléments de cette topologie des articles (du type topics DITA) :

  • Introduction, et /ou à propos
  • Utilisation
  • Prérequis
  • Exemple
  • Théorie
  • Astuces
  • Termes
  • Pièges à éviter

Pourquoi segmenter l’information ?

D’après notre expérience, écrire de la documentation logicielle n’a jamais été facile. La plupart des éditeurs de logiciel ne maîtrise pas le processus aisément.

Cette segmentation permet un guide rédactionnel plus précis. Cela permet, par ricochet, une recherche plus pertinente de l’information pouvant être réutilisée (au sein d’outils faisant du mono-source).

Les éditeurs n’emploient pas toujours des rédacteurs techniques qualifiés et les développeurs détestent écrire de la documentation. Notre approche à toujours consisté à penser que ces deux corps de métier peuvent et doivent travailler ensemble.