L'un des principes fondateurs de DITA est que l'information n'est pas monolithique : chaque unité de contenu répond à une intention précise. C'est la raison pour laquelle DITA définit plusieurs types de topics, chacun avec une structure XML propre et un usage spécifique. Connaître ces types et savoir choisir le bon est la compétence de base de tout rédacteur technique travaillant en environnement DITA.
Les types fondamentaux DITA : concept, task et reference
Les trois types de base constituent le socle de toute documentation DITA. Ils couvrent la grande majorité des besoins documentaires courants.
Le topic de type "concept" est conçu pour expliquer une idée, un terme ou un mécanisme. Il répond à la question "qu'est-ce que c'est ?" ou "comment cela fonctionne-t-il ?". Par exemple : "Qu'est-ce qu'un système de gestion de versions ?" ou "Comment fonctionne l'authentification à deux facteurs ?". Un concept ne doit pas contenir d'instructions procédurales — il informe, il n'explique pas comment faire.
Le topic de type "task" est le plus utilisé dans la documentation technique opérationnelle. Il décrit une procédure pas à pas et répond à la question "comment faire ?". Sa structure est stricte : un objectif, des prérequis optionnels, une série d'étapes numérotées, et un résultat attendu. Exemple : "Comment installer le module X" ou "Comment configurer le réseau". Cette rigueur structurelle garantit que toutes les procédures de la documentation sont présentées de façon homogène.
Le topic de type "reference" contient des données factuelles consultées ponctuellement, sans logique narrative. Listes de paramètres, tableaux de valeurs, descriptions de codes d'erreur, API de commandes : tout ce qui est consulté comme un dictionnaire ou une table de référence appartient à ce type.
Les types avancés : troubleshooting et glossary
Le topic de type "troubleshooting" a été introduit dans DITA 1.3 pour répondre aux besoins de documentation de résolution de problèmes. Sa structure associe un symptôme, une cause potentielle et une solution. Il est particulièrement adapté aux documentations de support technique, aux FAQ techniques et aux guides de diagnostic. Exemple : "Le système ne démarre pas" → cause → procédure de résolution.
Le topic de type "glossary" est dédié aux définitions de termes. Il permet de construire un glossaire structuré et réutilisable dans toute la documentation. Chaque entrée de glossaire est un topic indépendant, ce qui facilite la gestion et la réutilisation des définitions dans plusieurs publications.
Comment choisir le bon type de topic selon le contenu
La règle principale est simple : identifiez l'intention du lecteur. Si le lecteur veut comprendre un concept, utilisez un concept. S'il veut réaliser une action, créez une task. S'il cherche une valeur ou un paramètre précis, rédigez un reference. S'il rencontre un problème et cherche une solution, optez pour un troubleshooting.
Une erreur fréquente des rédacteurs qui débutent en DITA est de mélanger les intentions dans un même topic : expliquer un concept ET donner une procédure dans le même fichier. DITA impose de séparer ces intentions, ce qui paraît contraignant au début mais améliore considérablement la réutilisabilité et la clarté du contenu.
Cette discipline de pensée est l'une des compétences les plus valorisées chez un rédacteur technique en environnement DITA.
Découvrir la formation DITA chez Edvenn pour apprendre à maîtriser ces types de topics dans des cas pratiques réels.
Voir aussi la formation rédaction technique pour consolider les bases métier avant de vous spécialiser.