Rédaction technique : processus, formats et outils
Méthodes, formats et outils pour les rédacteurs techniques qui traitent la documentation comme une pratique d'ingénierie.
Un guide pratique du processus docs-as-code, de la définition du projet à la livraison - le blog, ce sont des essais et des analyses ; ici, c’est le manuel.
Que vous choisissiez entre DITA XML et Markdown, passiez à un workflow docs-as-code ou intégriez la documentation à votre pipeline CI/CD - ces guides couvrent les méthodes, formats et outils qui font de la documentation technique une pratique durable et évolutive.
Nouveau ici ? Commencez par ces quatre articles
Section intitulée « Nouveau ici ? Commencez par ces quatre articles »- Les trois niveaux de la documentation technique - situez où se trouve aujourd’hui la pratique documentaire de votre organisation
- Formats structurés et non structurés - le choix de format qui détermine tout le reste
- Cas concret : documentation de NuFirewall - la rédaction structurée en production, avec un résultat concret
- Intégrer la documentation aux processus de développement - le changement de workflow et d’outillage qui s’ensuit
Rédaction technique : un processus industriel
Section intitulée « Rédaction technique : un processus industriel »Définition du projetDéfinissez audience, périmètre et livrables avant d'écrire - les cinq paramètres que tout projet de rédaction technique doit fixer.
Intégrer la documentation aux processus de développementTraitez la documentation comme du code : même cadence de livraison, même contrôle de versions, même processus de revue.
Git : du fichier au contenuGit stocke des blobs de contenu, pas des noms de fichiers - comprendre ce modèle simplifie considérablement la gestion des branches et des diffs documentaires.
Voir les 19 articles →Formats source, référentiels, gestion de versions, traduction, livraison, et plus encore.
Format structuré DITA XML
Section intitulée « Format structuré DITA XML »Cas concret : documentation de NuFirewallLa presse a cité la documentation comme un atout produit, pas un supplément. Un regard détaillé sur les techniques DITA XML qui l'ont rendu possible.
Formats structurés et non structurésLes trois types de topics DITA - concept, tâche, référence - imposent une structure qui rend le contenu réutilisable, traduisible et cohérent.
Du document à la base documentaire modulaireRemplacez les manuels monolithiques par des modules de topics réutilisables : traductions moins coûteuses, revues parallèles, plusieurs formats de sortie à partir d'une seule source.
Voir les 5 articles →Formats structurés, cas d'usage DITA XML et compromis d'architecture documentaire.
L’argumentaire économique de la documentation structurée
Section intitulée « L’argumentaire économique de la documentation structurée »De la rédaction à la communication techniqueLa communication technique commence avant la vente - pourquoi ce rôle englobe le marketing, le journalisme et la documentation produit.
Les trois niveaux de la documentation techniqueUn modèle de maturité en trois niveaux - friche, documentation par sujets, DITA structuré - pour situer votre organisation et estimer ce que représente le niveau suivant.
Formats et outilsChoisissez votre format source avant votre outil - le format détermine l'enfermement propriétaire, les possibilités d'automatisation et les coûts à long terme.
Voir les 5 articles →Principe KISS, index PDF et l'argumentaire économique de la documentation structurée.
Didacticiels
Section intitulée « Didacticiels »Didacticiels DITA XML et XSL-FOMettez en place la chaîne de publication DITA XML vers PDF avec XSL-FO - de la rédaction des sources à la sortie mise en page, étape par étape.
Texte conditionnel avec SphinxGénérer des variantes de documents à partir des mêmes sources ReST avec le texte conditionnel de Sphinx.
Expressions régulières en PythonLa bibliothèque d'expressions régulières de Python aide à manipuler du texte, notamment si vous n'êtes pas familier avec sed ou awk.
Voir les 11 articles →Templates Jinja, automatisation SQL, sed et chaînes d'outils de documentation.