Un référentiel unique ?
Un référentiel Git unique pour la documentation technique maximise la réutilisation, la cohérence et la qualité, tout en simplifiant la collaboration en équipe.
Définition
Section intitulée « Définition »Idéalement, tout le contenu peut être placé sous un 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 → unique, par exemple le logiciel de 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 → Git. Ceci en maximise la réutilisation, la cohérence et la qualité. Si le contenu est au format 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 DocBookLangage de balisage XML sémantique destiné à la documentation technique, organisé en livres, chapitres et sections plutôt qu'en topics typés. Antérieur à DITA XML, il sert de point de comparaison habituel lors du choix d'un format structuré.Voir dans le glossaire →, par exemple, on peut exploiter au mieux les capacités de 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 → de ces formats pour le publier sous la forme appropriée.
Le contenu devient un réseau de modules d’information ; il faut alors gérer les relations au sein de ce réseau, notamment lors des mises à jour.
Référentiel unique
Compromis
Section intitulée « Compromis »En pratique, il semble que rares sont les entreprises qui ont franchi ce pas. Il est vrai que tant que les formats structurés ne seront pas enseignés dans le secondaire, il paraît utopique de vouloir y convertir tous les acteurs de la société, surtout si le turn-over y est important.
Voir aussi