Typologie de l'information

Par Olivier Carrère, rédacteur technique

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 :

Type d’information	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érence).
Sujet (topic) : 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-code, « sujet » (topic) désigne simplement une unité atomique de contenu. (Dans DITA, 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 Markdown/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 technique, issue de travaux tels que le minimalisme de John Carroll et l’Information Mapping de Robert Horn.

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/XSD.

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 Open Toolkit (DITA-OT), avec catalogues XML, scripts XSLT et moteurs XSL-FO.
- Idéal pour : Les organisations exigeant une rédaction structurée 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 source	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
OpenAPI	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.