Wiki — Versions de documentation

Chaque documentation avance par versions : on travaille dans un brouillon unique, puis on publie en nommant la version. Les lecteurs ne voient que la version publiée.

Description

Avant, une documentation n'avait qu'un seul contenu : toute modification était immédiatement en ligne, y compris l'enregistrement automatique qui tourne toutes les 5 minutes. Impossible de préparer une refonte tranquillement, ni de savoir quelle version avait été validée.

Désormais :

• les modifications alimentent un brouillon, invisible des lecteurs ;
• il n'existe qu'un seul brouillon par documentation — celui sur lequel tout le monde travaille ;
• à l'enregistrement, on choisit de rester en brouillon ou de publier ;
• publier fige le contenu dans une version numérotée (v1, v2, v3…) et nommée ;
• le numéro de la dernière version publiée est affiché sur la fiche et dans le panneau latéral ;
• les versions peuvent être renommées après coup, et une ancienne version peut être remise en ligne.

Accès

• Module : Wiki (ID 14170101)
• Écrans :
  • modification d'une documentation (/mod/14170101/update/{idwiki}) — brouillon et publication ;
  • fiche de lecture (/wiki/{idwiki}) — numéro de version, accès à l'historique des versions ;
  • panneau latéral de la fiche — ligne « Version », actions « Publier la version » / « Dépublier ».
• Droit requis : droit d'écriture (U) sur la documentation, ou être son auteur.

Fonctionnement

Enregistrer : brouillon ou publication

Le bouton Enregistrer de l'écran de modification n'écrit plus directement en ligne : il ouvre une fenêtre qui rappelle la version actuellement publiée et propose deux issues.

Le nom de la version est facultatif (100 caractères maximum) : sans nom, la version reste identifiée par son numéro.

Si vous n'avez pas touché au contenu — vous n'avez corrigé que le titre, les tags ou l'arborescence — la publication n'est pas proposée : ces informations ne sont pas versionnées, et publier créerait une version identique à celle en ligne. La fenêtre propose alors simplement Enregistrer les informations.

L'enregistrement automatique (toutes les 5 minutes) alimente le brouillon. Il ne peut donc plus publier une modification à votre insu.

Le titre, les tags, l'arborescence et l'image de couverture ne sont pas versionnés : ce sont des métadonnées, leurs modifications sont visibles immédiatement.

Consulter et gérer les versions

La fenêtre Versions (bouton en forme de branche dans la barre d'actions de la fiche, ou ligne « Version » du panneau latéral) liste le brouillon en cours et toutes les versions publiées : numéro, nom, statut, auteur, date. Elle permet de :

• comparer une version avec la précédente (texte supprimé barré, texte ajouté surligné). Pour une version très volumineuse, la comparaison n'est pas calculée automatiquement à l'ouverture — un bouton « Afficher la comparaison malgré tout » permet de la forcer. Le calcul se fait alors en arrière-plan (quelques secondes à quelques dizaines de secondes selon la taille) : une comparaison déjà demandée par quelqu'un d'autre sur ces mêmes contenus s'affiche instantanément ;
• renommer une version publiée ;
• remettre en ligne une version antérieure : elle redevient la version publiée, celle que voient les lecteurs. Aucune nouvelle version n'est créée — restaurer redésigne une version existante, ça ne fige pas un nouvel état. Le numéro affiché redevient le sien, l'historique est conservé intact, et l'opération est réversible dans les deux sens ;
• supprimer le brouillon en cours : à utiliser pour abandonner des modifications en cours de rédaction. La fiche retombe alors sur la dernière version publiée. Cette action n'est proposée que si la documentation a déjà été publiée au moins une fois : sur une documentation jamais publiée, il n'existe aucun contenu de repli, et supprimer le brouillon viderait la fiche plutôt que d'annuler des modifications. Elle reste possible même si le brouillon est soumis à validation.

Mettre en ligne / retirer de la ligne

Depuis le panneau latéral de la fiche :

• Publier le brouillon / Publier la version fige le brouillon en cours (ou, à défaut, le contenu actuel) et le met en ligne. L'action reste proposée sur une documentation déjà en ligne tant qu'un brouillon est en attente ;
• Dépublier retire la documentation de la ligne. L'historique des versions est conservé : la dernière version publiée reste la référence si la documentation est remise en ligne.

Remettre en ligne une documentation sans l'avoir modifiée ne crée pas de nouvelle version : son contenu est déjà celui de la dernière version publiée, il n'y a rien à figer. Le numéro ne bouge donc pas au fil des cycles dépublier / republier. Si vous saisissez un nom à cette occasion, il est appliqué à la version remise en ligne.

Ce que voient les lecteurs

Une personne sans droit d'écriture ne voit que la version publiée, sur toutes les surfaces : fiche de lecture, export PDF, envoi par mail, livrets, partages externes, recherche globale et assistants IA.

Corollaire : une documentation jamais publiée n'est visible que des personnes pouvant la modifier — comme c'était déjà le cas pour une documentation en brouillon.

Les brouillons ne remontent plus dans la recherche globale des autres utilisateurs ; leur auteur continue de retrouver les siens.

Statuts

Le statut de la fiche (Brouillon / En attente de validation / Publié) reste celui du panneau latéral et pilote la diffusion. Chaque version porte en plus son propre état :

Le circuit de validation

Soumettre à validation ne fige rien : c'est le même brouillon qui change d'étape. On peut donc continuer à l'amender pendant la relecture — le relecteur voit toujours l'état courant — et le reprendre en rédaction à tout moment (bouton sablier de la fenêtre Versions). Aucun numéro n'est attribué avant la publication : un refus ne consomme donc pas de numéro.

Une documentation déjà en ligne reste en ligne pendant la relecture de son brouillon. Une documentation jamais publiée, elle, passe « En validation » dans les listes — c'est ce qui permet à un relecteur de retrouver sa pile via le filtre de statut.

Le circuit est déclaratif : il n'y a ni notification au relecteur, ni droit distinct pour valider. Toute personne ayant le droit d'écriture peut soumettre, reprendre ou publier — la validation reste une convention entre personnes, désormais matérialisée sur la version plutôt que sur la fiche.

Reprise de l'existant

À la mise en place, chaque documentation a reçu son historique sans changer d'état de diffusion :

• documentation publiée → une version v1 nommée « Version initiale » ;
• documentation en brouillon → un brouillon, sans numéro ;
• documentation en attente de validation → un brouillon lui-même « en validation ».

Ces documentations n'affichent donc aucun numéro de version tant qu'elles ne sont pas publiées.

Récupération de l'historique antérieur

Avant le versionnement, les modifications de contenu n'étaient conservées que par le journal d'audit. Ces états successifs ont été repris comme versions à part entière : une documentation modifiée plusieurs fois par le passé retrouve donc son historique complet, consultable et comparable comme n'importe quelle version — la plus ancienne porte « Version initiale », et la version en ligne se retrouve en dernière position.

Deux limites tiennent à ce que le journal a réellement conservé :

• les contenus dépassant 64 Ko y étaient archivés tronqués : ils ont été écartés, pour qu'aucune version restaurable ne réécrive une documentation avec un contenu incomplet. Les documentations concernées gardent une lacune dans leur historique ;
• une modification qui n'a pas changé le contenu ne crée pas de version ;
• les documentations supprimées définitivement n'ont évidemment pas été recréées.

Le journal d'audit reste consultable en parallèle (sidebar → Activité → Historique), et couvre tous les champs, pas seulement le contenu.

Droits

Points d'attention

• Publier depuis la fenêtre « Modifier le statut » du panneau latéral crée aussi une version : il n'existe pas de mise en ligne sans version.
• La restauration est immédiate : la fenêtre de confirmation est la seule protection.
• Après avoir remis la v2 en ligne, la prochaine publication ne reprend pas le numéro 3 s'il a déjà existé : la numérotation continue au-delà du plus haut numéro atteint, un numéro n'est jamais réutilisé.
• Le numéro affiché est celui de la version en ligne, pas forcément le plus élevé : une documentation peut afficher « v2 » tout en ayant une v5 dans son historique.
• Modifier une documentation depuis une fiche (bouton Documentation d'un client, d'un matériel…) ne renomme plus la version en ligne. Le nom que vous avez donné à une version reste le vôtre : « Modification depuis une fiche » n'apparaît que sur les versions réellement créées par ce chemin. De même, enregistrer depuis une fiche sans rien changer au texte ne crée plus de version et ne fait plus disparaître le résumé.
• La comparaison entre deux versions n'est pas toujours proposée, et le message dit pourquoi : sur la toute première version, il n'y a rien avant elle à comparer ; sur un contenu très volumineux, la comparaison est différée et vous pouvez l'afficher malgré tout ; et si le service de comparaison est momentanément injoignable, un bouton « Réessayer » vous le dit tout de suite au lieu de vous laisser attendre. Le contenu de la version, lui, reste toujours accessible.

Documentation technique

Voir .claude/technical-docs/wiki/wiki-versioning.md.