Types d’information

Comprendre la typologie de l'information en rédaction technique : comment Concept, Tâche et Référence structurent le contenu selon l'intention du lecteur, et comment ce principe s'articule avec DITA, Markdown et OpenAPI.

Mis à jour en septembre 2026, 9 min de lecture

Voir en Markdown

Définition

La typologie de l’information (information typing) est la pratique consistant à catégoriser les contenus techniques en fonction de l’objectif immédiat et du mode cognitif du lecteur, plutôt que selon les fonctionnalités du produit ou un découpage arbitraire en chapitres.

Au lieu de rédiger des manuels monolithiques mélangeant théorie, instructions pas-à-pas et tableaux d’options dans un récit indifférencié, la typologie de l’information sépare le contenu en trois archétypes fonctionnels fondamentaux :

Concept

« Qu’est-ce que c’est ? »

Explique les idées, l’architecture, les principes, le contexte et les relations. Il construit le modèle mental du lecteur avant l’action.

Tâche

« Comment faire ? »

Fournit une procédure étape par étape pour accomplir une action précise avec un résultat vérifiable. Orienté vers l’action et linéaire.

Référence

« Quels sont les détails ? »

Fournit des données structurées, des paramètres de configuration, une syntaxe exacte et des tables de consultation. Destiné à un balayage visuel rapide par un lecteur qui sait déjà ce qu’il cherche.

Il s’agit de distinctions fonctionnelles fondées sur l’intention du lecteur et non de catégories littéraires rigides. Chaque unité documentaire existe pour répondre à un besoin utilisateur concret : comprendre un système, exécuter une manipulation ou vérifier une valeur précise.

Les trois types en pratique

Pour observer comment ces trois types s’articulent sur un même sujet, prenons l’exemple d’une intégration d’API :

Typage de l'informationLa discipline consistant à classer le contenu selon son objectif communicatif (concept, tâche, référence) plutôt que de rédiger une prose indifférenciée.Voir dans le glossaire →	Question principale	Intention première du lecteur	Exemple concret
Concept	Qu’est-ce que c’est ?	Comprendre des principes, l’architecture ou des règles métier	« Qu’est-ce que l’idempotence et pourquoi la logique de réessai l’exige-t-elle ? »
Tâche	Comment faire ?	Accomplir un objectif par des étapes séquentielles et concrètes	« Comment s’authentifier et effectuer sa première requête d’API ? »
Référence	Quels sont les détails ?	Consulter la syntaxe exacte, des paramètres, des schémas ou des codes	`POST /utilisateurs` - paramètres, schéma de requête, schéma de réponse, codes d’état

Intention principale et frontières de contenu

Structurer les contenus par type d’information ne signifie pas que les types soient mutuellement exclusifs en toutes circonstances :

Un sujet de type Concept peut intégrer un court extrait de code ou un schéma d’architecture pour illustrer un principe abstrait.
Un sujet de type Tâche peut inclure un bref rappel conceptuel dans ses prérequis ou son objectif pour expliquer la nécessité d’une étape.
Un sujet de type Référence intègre couramment des exemples concrets de syntaxe pour expliciter l’usage d’un paramètre.

La règle directrice est : garder le type d’information principal clair. Des éléments d’appui peuvent apparaître lorsque c’est nécessaire, mais tout contenu substantiel servant une autre intention du lecteur doit normalement être déplacé vers un sujet dédié de ce type et lié par hypertexte. Cela évite les « sujets hybrides » confus - des procédures submergées par des pages de théorie architecturale, ou des articles conceptuels encombrés de catalogues exhaustifs de paramètres.

Distinctions clés : hiérarchie terminologique

Les rédacteurs techniques rencontrent fréquemment des termes qui sont parfois confondus. Pour maintenir une rigueur conceptuelle, ce site distingue cinq notions précises :

Type d’information (information type) : L’objectif communicatif et l’intention première du lecteur (Concept, tâche, référenceLes trois types d'information de base de DITA XML : un concept introduit ou explique une idée, une tâche est une procédure numérotée, une référence est un contenu de consultation comme une liste de paramètres. Les articles de ce manuel sont eux-mêmes étiquetés selon ces trois types.Voir dans le glossaire →).
Sujet (TopicLa plus petite unité d'information autonome et titrée en DITA XML, typée comme concept, tâche ou référence et assemblée en documents via des ditamaps.Voir dans le glossaire →) : Une unité d’information modulaire et autonome traitant d’un sujet précis et structurée autour d’un seul type d’information principal. Dans la rédaction technique générale et le Docs-as-codeTraiter la documentation comme du code source : formats texte, gestion de versions, revue de code et CI/CD, plutôt qu'un processus de publication séparé.Voir dans le glossaire →, « sujet » (topic) désigne simplement une unité atomique de contenu. (Dans DITA XMLUne architecture de rédaction structurée et modulaire, construite autour de la typologie concept/tâche/référence et de la réutilisation de contenu via conrefs et ditamaps.Voir dans le glossaire →, au contraire, le terme possède une définition architecturale formelle encadrée par des contraintes strictes d’éléments XML et de règles d’héritage.)
Article / Page : L’unité de publication ou de présentation web effectivement délivrée au lecteur (par exemple, une page MarkdownLangage de balisage léger en texte brut, où la mise en forme s'exprime par une ponctuation simple, par exemple un # en début de ligne pour un titre. Facile à rédiger et à relire sous gestion de versions, il n'impose aucun schéma : les équipes docs-as-code compensent par des modèles et des contrôles automatisés. Ce manuel est rédigé en MDX, une variante de Markdown.Voir dans le glossaire →/MDX sur ce site).
Modèle (template) : Le guide de rédaction pratique précisant la structure recommandée, les sections et les niveaux de titre pour un type donné.
Format de document / syntaxe : La syntaxe de balisage ou de sérialisation du fichier source (comme Markdown, MDX, HTML, XML ou YAML).

Dans une approche docs-as-code, un auteur répond à un type d’information en adaptant un modèle de rédaction pour concevoir un sujet autonome, enregistré dans un format de document léger (comme Markdown) et publié sous la forme d’un article.

Métadonnées frontmatter : contentType

Pour rendre l’architecture de l’information lisible par machine et garantir sa cohérence au fil des contributions, chaque page de documentation déclare son type d’information dans ses métadonnées frontmatter :

---
title: "<Titre de l'article>"
description: "<Résumé en une phrase>"
contentType: concept # concept | task | reference
---

Quand est-il requis ? Tout sujet documentaire standard (un article expliquant un concept, détaillant une tâche ou fournissant des données de référence) doit obligatoirement renseigner contentType.
Valeurs acceptées : Strictement en minuscules : concept, task ou reference.
Pages volontairement non typées : Les index de section (index.mdx), les pages d’orientation ou de paliers (/learn, /process avec pageType: landing), les pages utilitaires (/ask, /about-this-blog avec pageType: utility) ou les synthèses d’architecture (pageType: overview) restent valides sans contentType.
Pourquoi ces métadonnées ? Elles permettent aux suites de tests automatisés (CI) et aux flux de l’API de vérifier la cohérence structurelle du corpus sans reposer sur des heuristiques de chemins fragiles.

Typologie de l’information et DITA

La typologie de l’information s’appuie sur une tradition établie en Communication techniqueLa discipline plus large qui couvre tout le cycle de vie du produit et touche le grand public, les prospects et les journalistes — par distinction avec la rédaction technique, qui produit la documentation produit destinée aux utilisateurs après la vente.Voir dans le glossaire →, issue de travaux tels que le Minimalisme (rédaction minimaliste)Une section tâche ne contient que ce qui est nécessaire pour accomplir la tâche — prérequis, étapes et quelques éléments étroitement liés — le contenu conceptuel et de référence étant placé ailleurs.Voir dans le glossaire → de John Carroll et l’Information Mapping de Robert Horn. Pour situer cette page dans cette tradition, voir le design de l’information et l’Information Mapping dans l’historique du site.

Plus tard, la norme DITA (Darwin Information Typing Architecture) a formalisé une architecture XML pour la typologie de l’information, en définissant des types de sujets standardisés : Concept, Tâche et Référence :

Le Concept correspond fonctionnellement au type de sujet DITA <concept>.
La Tâche correspond fonctionnellement au type de sujet DITA <task>.
La Référence correspond fonctionnellement au type de sujet DITA <reference>.

Cependant, une distinction architecturale essentielle doit être posée :

Nos modèles Markdown sont des canevas de rédaction pratiques et non des schémas DITA XML formels, et ils ne reposent pas sur des mécanismes de validation DTD (Document Type Definition)Le plus ancien langage de schéma XML : il déclare les éléments et les attributs qu'un document peut contenir, et dans quel ordre. DITA XML est distribué avec des DTD aussi bien qu'avec des schémas XSD.Voir dans le glossaire →/XSD (XML Schema Definition)Le langage de schéma XML du W3C, lui-même écrit en XML. Les schémas XSD de DITA XML définissent les éléments autorisés dans chaque type de topic ; un fichier qui ne les respecte pas échoue à la validation, ce qui limite aussi ce que les conrefs et le texte conditionnel peuvent produire.Voir dans le glossaire →.

Compromis d’ingénierie : DITA et le docs-as-code

Ni DITA ni Markdown / Astro ne sont universellement supérieurs ; ils répondent à des compromis d’ingénierie distincts adaptés à des contextes d’organisation différents :

Architecture DITA XML :
- Modèle sémantique formel : Balisage sémantique à granularité fine (<cmd>, <stepxmp>, <varname>, <filepath>).
- Validation par schéma : Application stricte de règles grammaticales via DTD, XML Schema ou RELAX NG. Tout élément mal positionné interrompt la compilation.
- Spécialisation et réutilisation : Hiérarchies de spécialisation puissantes et mécanismes d’inclusion fine par référence (<conref>).
- Chaîne de publication structurée : Traitement multicanal industriel via le DITA-OT (DITA Open Toolkit)Moteur de publication open source qui transforme des sources DITA XML, assemblées par un ditamap, en formats cibles comme le PDF (via XSL-FO) ou le HTML.Voir dans le glossaire → (DITA-OT), avec catalogues XML, scripts XSLT (XSL Transformations)Langage de transformation de documents XML en d'autres documents XML, HTML ou texte. Les chaînes de publication XML comme le DITA Open Toolkit utilisent des feuilles de style XSLT pour produire du HTML, ou du XSL-FO pour la sortie PDF.Voir dans le glossaire → et moteurs XSL-FOUn langage de feuilles de style pour transformer et mettre en page du contenu XML pour une sortie impression/PDF, couramment associé aux pipelines de publication DITA XML.Voir dans le glossaire →.
- Idéal pour : Les organisations exigeant une Rédaction structuréeRédiger un contenu dont le balisage encode le sens (ceci est un avertissement, ceci est une étape) plutôt que la seule apparence visuelle — permettant un traitement automatisé, une réutilisation et des contrôles de cohérence que les formats non structurés ne permettent pas.Voir dans le glossaire → formelle, la gestion de matrices complexes de variantes produits, la publication multisupport (PDF haute fidélité, aide en ligne) et des circuits de traduction globale centralisés.
Docs-as-code en Markdown / Astro :
- Environnement de rédaction simplifié : Contenus rédigés en Markdown et MDX lisibles et modifiables par tout intervenant.
- Collaboration Git-native : Revue de contenu intégrée aux pull requests et aux branches de développement.
- Faible surcharge d’outillage : Utilisation d’outils web modernes (Node.js, Astro, Starlight) sans chaîne de transformation XML complexe.
- Participation élargie : Ingénieurs, chefs de produit et rédacteurs collaborent au sein des mêmes dépôts de code.
- Discipline structurelle agile : La cohérence repose sur des modèles de rédaction pratiques (modèle concept, modèle tâche, modèle référence) et sur la validation de métadonnées frontmatter (contentType: concept | task | reference) plutôt que sur des parseurs XML contraignants.
- Idéal pour : Les projets logiciels à cycle court, les plateformes pour développeurs et les équipes souhaitant aligner la documentation sur les processus d’ingénierie logicielle.

Pour approfondir les enjeux des formats structurés et des bases modulaires, voir Formats structurés et non structurés ainsi que Du document à la base documentaire modulaire.

Comparatif pratique

Les différentes approches documentaires appliquent la typologie de l’information et le contrôle structurel à des niveaux de formalisation distincts :

Approche	Typage sémantique	Contrôle structurel	Format sourceLe format dans lequel le contenu est rédigé, par distinction avec le format cible vers lequel il est publié — la recette contre le plat.Voir dans le glossaire →	Cas d’usage type
Modèle Markdown libre	Convention éditoriale	Informel / relecture par les pairs	Markdown	Wikis d’équipe, notes de projet légères
Ce site (docs-as-code)	Types explicites + modèles + frontmatter	Schéma de métadonnées validé (`contentType`), tests de build	Markdown/MDX	Docs-as-code moderne, portails et manuels techniques
DITA	Types de sujets formels, hiérarchie de spécialisation	Schémas stricts (DTD, XSD, RELAX NG)	XML	Documentation industrielle multicanale, fabrication matérielle
OpenAPIFormat normalisé et lisible par machine (YAML ou JSON) qui décrit une API HTTP : endpoints, paramètres, schémas de requête et de réponse, codes d'état. La documentation de référence peut en être générée ; le rédacteur y ajoute les conseils d'usage que la description ne peut pas porter.Voir dans le glossaire →	Modèle de contrat d’API formel	Schémas et linters (JSON Schema, Spectral)	YAML / JSON	Description d’API HTTP lisible par machine, références générées

DITA et OpenAPI en perspective

DITA et OpenAPI répondent à des finalités complémentaires bien distinctes :

DITA fournit une architecture pour la prose documentaire rédigée par des humains à l’échelle de l’entreprise (manuels matériels, logiciels, guides d’exploitation).
OpenAPI modélise un contrat d’API HTTP lisible par machine. Il décrit avec exactitude les routes, verbes HTTP, paramètres de requête, corps JSON et codes d’état.

OpenAPI n’est pas un système de rédaction pour la prose ou les tutoriels, et DITA n’est pas un format de description de protocole conçu pour générer des consoles d’API interactives.

Typologie de l’information et documentation d’API

La documentation d’API illustre concrètement l’articulation entre les trois types d’information complémentaires et les contrats lisibles par machine :

Parcours du développeur à travers les types d’information : Concept, Tâche et Référence.

Les trois types dans les portails d’API

Concept (« Qu’est-ce que c’est ? ») :
- Exemple : « Qu’est-ce que l’idempotence et comment l’API traite-t-elle les clés de relecture ? »
- Périmètre : Vue d’ensemble de l’architecture, principes de sécurité (cycle de vie des jetons OAuth, scopes), quotas de débit et garanties de distribution des webhooks.
- Rôle : Apporte aux développeurs les bases conceptuelles indispensables pour concevoir une intégration robuste.
Tâche (« Comment faire ? ») :
- Exemple : « Comment s’authentifier et exécuter un premier appel d’API ? »
- Périmètre : Tutoriels linéaires avec prérequis explicites, configuration des identifiants, commandes curl exécutables et validation des réponses attendues.
- Rôle : Guide pas-à-pas le développeur vers un résultat opérationnel vérifiable.
Référence (« Quels sont les détails exacts ? ») :
- Exemple : POST /utilisateurs - paramètres, schéma de requête, schéma de réponse, codes d’état
- Périmètre : Verbes HTTP précis, routes, paramètres d’URL, en-têtes requis, schémas de payload JSON, codes de statut et formats d’erreur.
- Rôle : Permet une consultation rapide et faisant autorité pendant les phases de développement et de diagnostic.

OpenAPI et la couche de référence

OpenAPI décrit un contrat d’API dans un format exploitable par machine. Il peut étayer ou générer une grande partie de la couche de référence de la documentation d’API (comme les consoles interactives, les catalogues de paramètres et les définitions de types pour SDK).

Pour autant, la spécification OpenAPI ne se substitue pas à une documentation complète :

OpenAPI fournit la description et le contrat d’API exploitables par machine.
La documentation de référence présente ces informations de consultation sous une forme adaptée à la lecture humaine.
Les contenus Concept et Tâche explicitent les modèles mentaux, les contraintes architecturales et les flux d’intégration pas-à-pas qu’une description d’API seule ne peut communiquer de manière adéquate.

Un portail documentaire d’API réussi combine harmonieusement ces trois éléments : un contrat OpenAPI exploitable par machine alimentant la référence générée, enrichi d’articles Concept et de tutoriels Tâche rédigés par des auteurs techniques.

Pour concevoir des pages de référence d’endpoints, consultez le modèle de documentation d’API et explorez l’API propre à ce manuel.

Ressources connexes de la boîte à outils

Modèle d’article concept - Canevas Markdown pratique pour les articles conceptuels.
Modèle d’article tâche - Canevas Markdown pratique pour les procédures séquentielles.
Modèle d’article référence - Canevas Markdown pratique pour les données de consultation.
Modèle de documentation d’API - Déclinaison de référence dédiée aux endpoints d’API REST.
Exemple : une page Markdown bien structurée - Exemple annoté illustrant la mise en œuvre d’un article concept.
Formats structurés et non structurés - Analyse comparative approfondie entre DITA XML et la publication non structurée.