Tronc
Dépôt principal conservant toutes les versions des fichiers placées au cours du temps par le rédacteur technique (ou plus fréquemment, le développeur).
Les systèmes de gestion de versions - rustiques mais fiables
Gérez la documentation technique avec Git ou Subversion comme du code source : suivez les modifications, collaborez en équipe et restaurez des versions.
Définition
Section intitulée « Définition »Travailler sur des fichiers sources au format texte, et non binaire, est l’occasion pour le rédacteur technique de gérer son contenu comme les développeurs gèrent leur code : sous un système de gestion des sources tel que Git ou Subversion (ou, historiquement, SourceSafe, abandonné vers 2010).
Principes clés
Section intitulée « Principes clés »Ces systèmes :
- favorisent le travail de groupe,
- suppriment les copies de fichiers en doublons et
- réduisent le risque de perte de données à presque zéro.
Sur des fichiers texte, et non binaires, un système de gestion de version offre des fonctionnalités supérieures :
- pas de risque de pertes de données en cas de défaillance du réseau,
- possibilités de travail off-line (déconnecté) poussées,
- non-verrouillage des fichiers par les membres de l’équipe qui les ont ouverts,
- possibilité de restauration très fine et dans le temps (depuis le dernier dépôt du fichier sur le 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 →) et en termes de quantité de travail.
Le système 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 → conserve l’historique des modifications.
Des interfaces graphiques permettent d’utiliser directement sous les gestionnaires de fichiers ces outils originellement conçus pour être utilisés en ligne de commande. Cependant, le paradigme sur lequel ils reposent est parfois difficile à appréhender pour les publics les moins technophiles.
Les systèmes de gestion des sources utilisent les concepts suivants :
Branche
Dépôt secondaire créé à partir de la version principale du code source.
Tag
Instantané du tronc ou d’une branche à un instant t. Permet de figer facilement une version, par exemple, la version publiée, et de créer une archive.
Si l’on s’en donne la peine, il est également possible de mal utiliser les systèmes de gestion de version et de perdre des données. Mais, en pratique, à même niveau d’effort et de compétence, le risque de perdre des données est nettement moindre si le rédacteur technique manipule des fichiers texte sous un gestionnaire de version plutôt que des fichiers binaires sur un répertoire partagé.
Les systèmes de gestion de code source ont une fiabilité éprouvée et gèrent des millions de lignes de code. Tout comme les systèmes de fichiers (Ext4, Btrfs, etc.) ils évoluent lentement, selon une politique conservatrice, et ne sont proposés en production que lorsqu’ils ont été exhaustivement débogués. Si les plus grands projets de développement informatique, tel que GNU/Linux, par exemple, leur font confiance, pourquoi ne pas également leur confier la documentation technique ?
Compromis
Section intitulée « Compromis »Un bémol cependant : ces outils ne sont pas destinés spécifiquement au format XML et effectuent des comparaisons ligne par ligne entre les fichiers, et non pas nœud par nœud, ce qui multiplie inutilement les conflits entre les commits ou les branches.
Voir aussi