Check-list : adoption du docs-as-code
- 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 : Markdown pour la simplicité, DITA XML si la réutilisation de contenu et le single-sourcing sont réellement requis - voir formats et outils.
Gestion de versions
Section intitulée « Gestion de versions »- Un référentiel 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.
- 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
Section intitulée « Processus de revue »- Les changements documentaires suivent le même flux de revue par pull request 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
Section intitulée « 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.