Adopter le docs-as-code
Traiter la documentation comme du code : Git, Markdown, pull requests, CI/CD et pipelines de publication statique.
Le 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 → ne se résume pas à stocker la documentation dans Git. C’est un workflow d’ingénierie : la documentation est rédigée dans des formats source texte, conservée sous Gestion de versionsEnregistrement de chaque modification d'un ensemble de fichiers, qui permet de restaurer n'importe quel état antérieur, de comparer les changements et de travailler à plusieurs en parallèle. Git est le logiciel de gestion de versions le plus répandu ; en docs-as-code, la documentation est placée sous gestion de versions à côté du code du produit.Voir dans le glossaire → à côté du produit, modifiée dans des branches, relue par Pull requestDemande d'intégration des modifications d'une branche dans la ligne principale, présentée sous forme de différences à relire : les relecteurs commentent, les contrôles automatisés s'exécutent et l'approbation est tracée avant la publication. GitLab parle de merge request.Voir dans le glossaire →, vérifiée automatiquement et publiée par un pipeline. Cette section suit l’ordre dans lequel une équipe l’adopte généralement : pourquoi, Git, conception du RéférentielL'endroit où une équipe documentaire conserve ses sources : répertoires partagés, base de données d'un CMS ou système de gestion de versions comme Git, qui conserve en outre l'historique complet de chaque fichier. Un référentiel Git est aussi appelé dépôt.Voir dans le glossaire →, branches, puis CI/CD (intégration continue et livraison continue)Automatisation qui vérifie chaque modification dès qu'elle est proposée (intégration continue), puis publie le résultat une fois les contrôles réussis (livraison continue). En docs-as-code, un pipeline CI/CD compile la documentation, exécute des tests, comme la vérification des liens et des schémas, et déploie le site.Voir dans le glossaire → et revue.
Pourquoi le docs-as-code ?
Section intitulée « Pourquoi le docs-as-code ? »Conception du référentiel
Section intitulée « Conception du référentiel »Branches
Section intitulée « Branches »Formats source et publication
Section intitulée « Formats source et publication »CI/CD et revue documentaire
Section intitulée « CI/CD et revue documentaire »Vous travaillez avec 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 → ou le Single-sourcingGénérer plusieurs livrables (PDF, HTML, formats d'aide) à partir d'une source unique, plutôt que de maintenir une source séparée par format de sortie.Voir dans le glossaire → ? Voir choisir un modèle de rédaction. Vous cherchez les didacticiels de traitement de texte et d’automatisation ? Voir automatisation et techniques spécialisées. Pour voir comment un site docs-as-code peut aussi servir son contenu à des scripts et à des assistants IA, voir l’API de ce manuel.