Utiliser la rédaction structurée

La discipline du typage de l’informationTypage 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 → : découper le contenu en concepts, tâches et références réutilisables et assemblables en différents livrables. DITA XMLDITA 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 → en est la mise en œuvre la plus formelle, et celle que cette section documente en détail ; les mêmes principes peuvent s’appliquer avec des formats plus légers, comme le montrent la page typologie de l’information et les modèles de la boîte à outils.

Formats et architecture

Typologie de l'informationConcept, tâche et référence : le typage sur lequel repose la rédaction structurée, en DITA comme en Markdown.

Formats structurés et non structurésLe choix fondamental qui détermine réutilisation, coûts de traduction et outillage.

Cas concrets d'utilisation de DITA XMLDes solutions de rédaction structurée en conditions réelles.

Complexité de l'architecture documentaireQuand une architecture documentaire devient trop complexe — et comment le reconnaître.

Du document à la base documentaire modulairePasser de documents monolithiques à une base de contenu modulaire et réutilisable.

Cas concret : documentation de NuFirewallLa rédaction structurée en production, issue d'un projet open source salué par la presse.

Didacticiels

Didacticiels DITA XML et XSL-FORédiger en DITA XML et générer du PDF avec des feuilles de style XSL-FO.

Insérer automatiquement des données dans un fichier DITA XMLInsérer dynamiquement des données produit dans des topics DITA.

Texte conditionnel avec Jinja (méthode objet)Définir audience, plateforme et version comme objets Python, puis filtrer le contenu à la génération.

Texte conditionnel avec JinjaUn script de prétraitement Python qui inclut ou retire des sections de contenu avant génération.

Texte conditionnel avec Sphinx/ReSTGénérer des variantes de documents à partir des mêmes sources ReST.

Insérer automatiquement des données dans un fichier reStructuredTextTemplater un fichier ReST pour que Python y insère noms et versions produit à la génération.

Insérer automatiquement des données SQL dans un fichier reStructuredTextInterroger une base de données produit et injecter les résultats directement dans la documentation.

Encore en train d’arbitrer entre DITA et MarkdownMarkdownLangage 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 → ? Voir choisir un modèle de rédaction.