Check-list : adoption du docs-as-code

Check-list

À associer à adopter le docs-as-code pour la version narrative de chaque étape ci-dessous.

Format

• Le contenu est (ou sera) stocké dans un format texte, non binaire - voir format source. Les formats binaires (Word, FrameMaker) ne peuvent pas être comparés ou fusionnés de manière significative.
• Le format choisi correspond aux besoins réels de l’équipe : 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 → pour la simplicité, 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 → si la réutilisation de contenuRéutilisation du contenu (réutilisation de contenu)Rédiger une information une seule fois et l'employer à plusieurs endroits ou dans plusieurs livrables plutôt que de la recopier : une correction faite une fois s'applique partout. Les conrefs, le texte conditionnel et le single-sourcing sont autant de moyens d'y parvenir.Voir dans le glossaire → et le single-sourcingSingle-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 → sont réellement requis - voir formats et outils.

Gestion de versions

• Un référentielRé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 → existe et sa structure a été décidée délibérément - voir le référentiel et un référentiel unique ?.
• Les rédacteurs qui ne sont pas encore à l’aise avec Git disposent d’un chemin d’apprentissage - binôme avec un développeur, atelier interne court, ou commandes courantes documentées. Ne présumez pas d’une maîtrise de Git par défaut.
• Une stratégie de branches est décidée avant d’en avoir besoin sous la pression d’une échéance - voir utiliser les branches.

CI/CD

• La documentation se génère automatiquement à chaque changement, de la même manière que le code - voir intégrer la documentation aux processus de développement.
• Un échec de build bloque la fusion de la même manière qu’un test qui échoue - une documentation cassée ne devrait pas partir en production silencieusement.
• Des builds de prévisualisation permettent aux relecteurs de voir le rendu final, pas seulement le diff du texte source.

Processus de revue

• Les changements documentaires suivent le même flux de revue par pull requestPull 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 → que le code, pas un processus séparé et plus laxiste.
• La check-list de revue technique est utilisée de manière cohérente, pas de façon improvisée selon le relecteur.

Préparation de l’équipe

• Les rédacteurs disposent d’environnements locaux fonctionnels (éditeur, client Git, outillage de build) avant la date de migration, pas le jour même.
• Un plan de retour arrière vers l’ancien processus existe, au cas où le nouveau nécessiterait un temps de mise au point avant d’être digne de confiance pour de vraies livraisons.