Rédaction structurée DITA en YAML
Mise en œuvre concrète et opérationnelle des principes DITA (tâche, concept, référence) en YAML, avec validation stricte et rendu sémantique sans XML.
Cette sous-section présente une mise en œuvre concrète d’architecture documentaire structurée inspirée de la norme OASIS DITA. Les rédacteurs définissent des sujets dans des fichiers YAML autonomes, validés par un schéma strict et convertis automatiquement en HTML sémantique et accessible au sein du site.
Présentation de l’approche
Traditionnellement, la rédaction structurée DITA (Darwin Information Typing Architecture) exige des fichiers XML, des DTD ou schémas XSD complexes, et la chaîne de traitement DITA Open Toolkit (DITA-OT). Cette lourdeur technique freine souvent l’adoption du typage de l’information dans les environnements docs-as-code modernes.
Notre mise en œuvre adopte une approche intermédiaire : capturer la **rigueur sémantique de DITA** (séparation tâche/concept/référence, distinction entre commande impérative et information complémentaire, sous-étapes ordonnées, choix alternatifs, résultats vérifiables) au moyen de **fichiers YAML lisibles** et aisément gérables dans Git.
Exemples opérationnels
Explorez les trois sujets de référence opérationnels générés à partir des fichiers YAML du projet :
Remplacer une lame de tondeuse à gazon
Déposer une lame rotative usée ou endommagée et installer une lame neuve en respectant les consignes de sécurité mécanique.
Le typage de l’information en documentation technique
Comprendre les principes fondamentaux de la rédaction structurée modulaire et la séparation entre tâches, concepts et références.
Données de référence indicatives : Caractéristiques et paramètres d’entretien de la lame de tondeuse
Spécifications techniques indicatives, exemples de couples de serrage, tolérances d’usure et critères de remplacement pour lames de tondeuses rotatives.
Choisir le bon type d’information
Le principe fondamental du typage de l’information (information typing) repose sur l’autonomie et la clarté d’intention de chaque sujet :
Instructions procédurales
Pour accomplir une action concrète avec un résultat vérifiable.
- Question : Comment faire ?
- Structure : Prérequis, contexte, étapes ordonnées, résultats.
- Règle : Au moins une étape (`cmd`) obligatoire.
Information explicative
Pour comprendre les principes, l’architecture et le fonctionnement général.
- Question : Qu’est-ce que c’est ? Pourquoi ?
- Structure : Introduction, sections, sous-sections, exemples.
- Règle : Jamais de procédure déguisée en concept.
Information factuelle et consultation
Pour vérifier rapidement des spécifications, options, cotes ou paramètres.
- Question : Quels sont les paramètres ?
- Structure : Tableaux structurés, paires clé/valeur, code.
- Règle : Optimisé pour le balayage visuel, non narratif.
Correspondance YAML vers HTML
Le tableau ci-dessous explicite comment les structures déclaratives YAML se traduisent directement en HTML sémantique standard sans dépendre d’artifices graphiques ou de scripts clients :
| Construct DITA / YAML | Balise HTML générée | Rôle sémantique et accessibilité |
|---|---|---|
prereq | <section class="dita-prereq"> <ul> | Conditions préalables à vérifier avant de commencer |
context | <section class="dita-context"> <p> | Contexte et raison d’être de l’intervention |
steps | <ol class="dita-steps"> | Séquence ordonnée numérotée avec compteurs CSS |
step | <li class="dita-step"> | Étape élémentaire de la procédure |
cmd | <div class="dita-cmd"> | Instruction impérative principale (mise en valeur) |
info | <div class="dita-info"> | Information complémentaire explicative |
substeps | <ol class="dita-substeps" type="a"> | Sous-étapes ordonnées subordonnées (a, b, c) |
choices | <ul class="dita-choices"> | Alternatives non ordonnées (distinctes des étapes) |
stepresult | <div class="dita-stepresult"> | Résultat attendu d’une étape spécifique |
result | <section class="dita-result"> | Résultat global de fin de procédure |
postreq | <section class="dita-postreq"> | Actions ultérieures, vérifications ou nettoyage |
tables | <table> <thead> <tbody> | Tableau accessible avec cellules th d’en-tête et de portée |
notes | <aside role="note"> | Encadré sémantique (note, conseil, attention, danger) |
related | <nav class="dita-related-links"> | Liens typés groupés par nature (tâche, concept, référence) |
Guide de rédaction et flux de travail
Pour ajouter un nouveau sujet structuré à la documentation :
- 1. Créer le fichier YAML
Créez un fichier dans `src/content/dita/en/<id>.yaml` (et son équivalent dans `src/content/dita/fr/<id>.yaml`). L’identifiant `id` doit correspondre au nom du fichier.
- 2. Déclarer le type et la structure
Définissez `type: task`, `type: concept` ou `type: reference`. Remplissez obligatoirement `title` et `shortdesc`.
- 3. Valider localement
Exécutez `npm run validate:dita` ou `npm test`. Le validateur vérifie la syntaxe, la conformité au schéma et l’existence de tous les liens associés.
- 4. Prévisualiser dans Astro
Lancez `npm run dev` et ouvrez `http://localhost:4321/<lang>/structured-authoring/dita-yaml/<id>/` pour vérifier la mise en page.
Périmètre et exclusions volontaires
Ce système est volontairement conçu comme une implémentation ciblée des principes de rédaction structurée, et non comme un processeur DITA complet :
- Pas de balisage inline ultra-fin: Les éléments DITA tels que `uicontrol`, `wintitle`, `filepath`, `userinput`, `systemoutput` ou `varname` ne disposent pas de balises YAML dédiées. La syntaxe Markdown standard (code en ligne, gras) suffit amplement et garde le texte lisible.
- Pas de chaîne XML ni DITA-OT: Aucune transformation XSL-FO complexe n’est nécessaire ; les pages sont assemblées nativement par Astro sous forme de HTML statique.
- Pas de DITA maps ni conref: La navigation est gérée par l’architecture de site existante (Starlight), et les réutilisations de blocs se font via des composants Astro modulaires.
Validation locale automatisée
Pour garantir qu’aucune structure invalide n’arrive en production, plusieurs commandes de vérification sont à la disposition des rédacteurs :
# Validation dédiée des fichiers YAML DITA :
npm run validate:dita
# Suite complète de tests unitaires et d’intégration :
npm test
# Validation de l’architecture de l’information du site :
npm run validate:ia