# Typologie de l'information ## 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. ## 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 : ```yaml --- title: "" description: "" 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 ``. - La Tâche correspond fonctionnellement au type de sujet DITA ``. - La Référence correspond fonctionnellement au type de sujet DITA ``. Cependant, une distinction architecturale essentielle doit être posée : > **Note: Distinction fondamentale** > > **Le site applique le même principe général de typologie de l'information que DITA, mais le met en œuvre au moyen de conventions de rédaction légères en Markdown / Astro plutôt que par des schémas DITA XML.** 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 (``, ``, ``, ``). - **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 (``). - **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](https://docs.redaction-technique.org/fr/toolkit/concept-article-template/), [modèle tâche](https://docs.redaction-technique.org/fr/toolkit/task-article-template/), [modèle référence](https://docs.redaction-technique.org/fr/toolkit/reference-article-template/)) 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](https://docs.redaction-technique.org/fr/formats/structured-vs-unstructured-formats/) ainsi que [Du document à la base documentaire modulaire](https://docs.redaction-technique.org/fr/formats/modular-documentation/). --- ## 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 : ```mermaid %%{init: {"flowchart": {"curve": "basis"}, "themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif", "clusterBkg": "#f1f5f9", "clusterBorder": "#64748b"}}}%% flowchart TD accTitle: Parcours du développeur à travers les types d'information accDescr: Progression séquentielle à travers les trois types d'information, de la compréhension des concepts à la réalisation d'une tâche puis à la consultation des spécifications. subgraph S1["1. Concept — Comprendre le domaine"] C1["Qu'est-ce que l'idempotence ?
Architecture, modèle d'authentification, objets clés"] end subgraph S2["2. Tâche — Accomplir une procédure"] T1["Comment faire un premier appel ?
Prérequis, échange de jeton, commandes curl"] end subgraph S3["3. Référence — Consulter les détails"] R1["POST /users — paramètres et schémas
Verbe HTTP, chemin d'endpoint, modèles JSON"] end S1 --> S2 --> S3 classDef stage fill:#e2e8f0,stroke:#3b82f6,color:#1e293b,stroke-width:1.5px,font-weight:600 classDef step fill:#f1f5f9,stroke:#64748b,color:#0f172a,stroke-width:1.5px class S1,S2,S3 stage class C1,T1,R1 step linkStyle default stroke:#64748b,stroke-width:1.5px ``` **Parcours du développeur à travers les types d'information : Concept, Tâche et Référence.** ### Les trois types dans les portails d'API 1. **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. 2. **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. 3. **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](https://docs.redaction-technique.org/fr/toolkit/api-documentation-template/) et explorez [l'API propre à ce manuel](https://docs.redaction-technique.org/fr/about-the-api/). --- ## Ressources connexes de la boîte à outils - [Modèle d'article concept](https://docs.redaction-technique.org/fr/toolkit/concept-article-template/) — Canevas Markdown pratique pour les articles conceptuels. - [Modèle d'article tâche](https://docs.redaction-technique.org/fr/toolkit/task-article-template/) — Canevas Markdown pratique pour les procédures séquentielles. - [Modèle d'article référence](https://docs.redaction-technique.org/fr/toolkit/reference-article-template/) — Canevas Markdown pratique pour les données de consultation. - [Modèle de documentation d'API](https://docs.redaction-technique.org/fr/toolkit/api-documentation-template/) — Déclinaison de référence dédiée aux endpoints d'API REST. - [Exemple : une page Markdown bien structurée](https://docs.redaction-technique.org/fr/toolkit/example-markdown-page/) — Exemple annoté illustrant la mise en œuvre d'un article concept. - [Formats structurés et non structurés](https://docs.redaction-technique.org/fr/formats/structured-vs-unstructured-formats/) — Analyse comparative approfondie entre DITA XML et la publication non structurée. --- Source: https://docs.redaction-technique.org/fr/toolkit/information-types/