Référentiel
Le contenu technique est un capital immatériel précieux. Découvrez comment choisir et gérer un référentiel documentaire pour le versionner, le protéger et le partager.
Définition
Section intitulée « Définition »Le contenu est le capital immatériel de la société et doit être protégé comme tel. Il peut être géré dans différents référentiels : répertoires, mais aussi outils de gestion de contenu d’entreprise et logiciels 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 →.
Pourquoi ce choix compte
Section intitulée « Pourquoi ce choix compte »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 → détermine en grande partie ce qu’une équipe peut faire de son contenu :
- Travailler à plusieurs. Deux rédacteurs peuvent-ils modifier le même contenu sans que l’un perde le travail de l’autre ?
- Restaurer le contenu. Avec quelle précision une modification perdue ou indésirable peut-elle être restaurée, et par qui ?
- Tout modifier d’un coup. Une modification transverse, comme le chemin de toutes les images, est-elle une seule opération ?
- Gérer versions et langues. Comment s’organisent les traductions et les versions parallèles de la documentation ?
Les référentiels comparés
Section intitulée « Les référentiels comparés »Le choix du référentiel adapté au travail de groupe est déterminant : les répertoires réseau partagés présentent des limites importantes, les CMS apportent un workflow pratique mais avec leurs propres compromis de fiabilité, et les systèmes de gestion de versions offrent une solution bien plus fiable.
| Travailler à plusieurs | Restaurer le contenu | Tout modifier d’un coup | |
|---|---|---|---|
| Répertoire réseau partagé | Fichiers ouverts verrouillés, ou la dernière sauvegarde écrase les autres | Répertoire par répertoire, à partir de sauvegardes souvent seulement quotidiennes | Impossible tant que les fichiers sont verrouillés |
| CMS (Content Management System)Un outil qui ajoute workflow et verrouillage des fichiers à la gestion de contenu, au prix de compromis de fiabilité par rapport à une gestion de versions simple.Voir dans le glossaire → | Les rédacteurs téléchargent une copie locale puis la renvoient ; le CMS verrouille les fichiers en cours de modification | Fiabilité à tester, avec une stratégie de sauvegarde | Un CMS sur base SQL ne permet pas la recherche-remplacement sur l’ensemble du contenu |
| Système de gestion de versions | Pas de verrouillage ; les branches permettent de travailler en parallèle | Très fine ; chaque clone Git contient tout l’historique | Une opération ordinaire sur des fichiers texte |
La gestion de versions a aussi ses limites : elle compare les fichiers ligne par ligne, et non nœud par nœud, et son paradigme est parfois difficile à appréhender pour les publics les moins technophiles. Un CMS reste pertinent lorsque les contributeurs ne peuvent pas travailler avec des fichiers texte et un gestionnaire de versions.