Utiliser les branches des systèmes de gestion de sources
Utilisez les branches Git pour gérer des projets documentaires parallèles, des variantes produit et des workflows de traduction sans conflits - guide pratique rédacteur.
Définition
Section intitulée « Définition »Les systèmes de gestion de sources proposent de créer des branches d’un projet : si à un moment donné, un projet se divise en deux projets incompatibles, une BrancheLigne de travail parallèle dans un système de gestion de versions : les modifications faites sur une branche restent isolées jusqu'à leur relecture et leur fusion dans la ligne principale, ce qui permet de faire avancer en même temps plusieurs rédacteurs, versions ou langues.Voir dans le glossaire → est créée à partir du projet principal. Le rédacteur technique peut ainsi gérer les différentes traductions de la documentation technique.
Principes clés
Section intitulée « Principes clés »Le système des branches peut servir en théorie à gérer :
- les différentes traductions d’une documentation technique,
- les différentes variations d’une même documentation technique.
Variations : préférer le texte conditionnel
Section intitulée « Variations : préférer le texte conditionnel »En pratique, cependant, il vaut mieux gérer les déclinaisons d’une même documentation à l’aide des mécanismes de partage de sections et de filtrage de Texte conditionnelContenu marqué comme ne s'appliquant qu'à un public, une version de produit ou un livrable donnés, afin qu'une même source puisse être filtrée à la compilation pour produire des documents différents. DITA XML le met en œuvre avec les fichiers ditaval ; des moteurs de modèles comme Jinja font de même pour les formats texte.Voir dans le glossaire → des outils de documentation.
Traductions : tout dépend du système
Section intitulée « Traductions : tout dépend du système »D’autre part, le système de gestion des branches est plus ou moins adapté à la gestion des traductions selon le gestionnaire de sources que l’on utilise.
La principale différence entre les systèmes de gestion de sources Git et Subversion, c’est leur manière de gérer les branches. Créer une branche sous Subversion revient à dupliquer un répertoire. Les fichiers des deux répertoires évoluent ensuite séparément. Sous Git, en revanche, la création de branche se fait sans duplication de données. Sur un même répertoire local, une commande permet de changer de branche.
Traductions : copier ou créer une branche ?
Section intitulée « Traductions : copier ou créer une branche ? »Créer une traduction d’une documentation consiste à forker, soit créer une branche, le document initial. Si l’on utilise Git se pose alors le choix entre :
- copier le répertoire de la langue source,
- créer une branche sur le répertoire de la langue source.
La solution de la branche permet en théorie d’effectuer du Cherry picking et d’appliquer facilement à toutes les langues cibles des modifications affectant uniquement le code XML du projet.
Exemples
Section intitulée « Exemples »Par exemple, une modification de
<image href="filter.png" placement="break"/>en
<image href="filter.png" placement="break" scalefit="yes"/>de la version anglaise de la documentation peut facilement être appliquée aux versions chinoise, française, allemande ou autre si elle a fait l’objet d’un CommitInstantané enregistré des modifications apportées à un dépôt Git, accompagné d'un auteur, d'une date et d'un message qui explique le changement. La suite des commits forme l'historique du projet, point de départ des branches et base de comparaison pour les relecteurs et les traducteurs.Voir dans le glossaire → distinct. En pratique, cependant, cette opération peut s’avérer délicate et n’être réellement utile que si l’on doit gérer un grand nombre de différentes versions linguistiques. En tout cas, la solution des branches autorise de telles opérations, non celle des répertoires. Elle est cependant plus difficile à appréhender et à utiliser par l’équipe de rédaction technique.
Voir aussi