Choisir un modèle de rédaction

Outils, formats, compromis et critères de sélection pour la documentation technique.

1 min de lecture

Les décisions qui conditionnent tout le reste : le degré de structure formelle dont votre contenu a besoin, la manière de le réutiliser, le 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 → dans lequel rédiger et les formats cibles vers lesquels publier.

Les principes du contenu structuré (séparer le fond de la forme, typer l’information selon l’intention du lecteur, rédiger des modules réutilisables) s’appliquent à presque tous les projets documentaires. Ce qui varie, c’est la rigueur avec laquelle ils sont imposés. 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 → les impose par un schéma et une chaîne d’outils dédiée ; le 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 →, dans un workflow 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 →, les applique par convention, par des modèles et par des contrôles automatisés. Aucune des deux approches n’est obsolète, et aucune n’est supérieure dans l’absolu : chaque projet appelle un niveau de structure formelle différent.

Markdown

Le Markdown comme format sourceUn format source léger et versionnable, à mi-chemin entre le traitement de texte et le XML structuré.

Une page Markdown bien structuréeUn article concept annoté, expliquant chaque choix structurel.

Rédaction structurée

Utiliser la rédaction structuréeDITA XML, typage de l'information, réutilisation de contenu et modèles de contenu modulaires — avec des études de cas réelles.

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

DITA

Format structuré DITA XMLRéduisez les coûts et délais en rédaction technique en choisissant le bon format d'authoring structuré et en optimisant la réutilisation du contenu documentaire.

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.

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

Réutilisation de contenu

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

Formats source et cible

Format sourceChoisir dans quoi vous rédigez — la décision qui détermine toute votre chaîne d'outils.

Format cibleChoisir vers quoi vous publiez, et pourquoi ce n'est pas forcément le même format que la source.

Formats et outilsPourquoi le format compte plus que l'outil — et comment évaluer le coût de l'outillage.

Vous comparez des chaînes docs-as-code ? Voir adopter le docs-as-code. Vous cherchez les didacticiels Jinja, Sphinx/ReST ou 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 → ? Voir automatisation et techniques spécialisées.