Comment créer un historique de révision de document

En bref

• L'historique des révisions est l'artefact (une table) ; le contrôle de version est la pratique qui garantit sa précision.
• Colonnes minimales : version, date, auteur, description, référence à la version précédente, vérifié par.
• Ajout uniquement : corrigez une entrée erronée avec une nouvelle ligne, jamais en modifiant l'ancienne.
• Une entrée que personne n'a vérifiée par rapport à la véritable modification est une réclamation, pas un enregistrement.
• QueryChart le génère automatiquement via son journal des modifications : voir /features/version-control.

La table est un record, pas la discipline

Un historique des révisions est le tableau que la plupart des lecteurs imaginent immédiatement : un numéro de version, une date, le nom de la personne qui a effectué la modification, une brève description de ce qui a changé et souvent le nom de celui qui l'a révisé. Il s'agit d'un artefact : des lignes dans un tableau, généralement situées sur la page de garde du document. Le contrôle de version est la différence qui produit ces lignes : la pratique consistant à ne jamais modifier un document contrôlé sans en écrire un, à ne jamais réécrire une entrée après coup et à demander à quelqu'un d'autre que l'éditeur de vérifier l'entrée par rapport à la modification. Un document peut contenir un historique complet des révisions sans toutefois avoir de véritable contrôle de version, si personne n'a jamais vérifié une seule ligne par rapport à ce qui a réellement changé.

Traitez l'historique des révisions comme un objet distinct du document qu'il décrit, et non comme une section à l'intérieur de celui-ci. Le document change ; le journal ne fait que croître. Chaque entrée nécessite un numéro de version, une date, un auteur, une description claire de ce qui a changé et pourquoi, une référence à la version qu'elle remplace et, la colonne que la plupart des tableaux construits à la main oublient, qui a vérifié l'entrée par rapport à la véritable modification. Sautez cette dernière colonne et le journal est un ensemble de réclamations non vérifiées : le récit d'un auteur sur sa propre modification, déposé par la même personne qui l'a effectuée.

Le tableau ci-dessous présente un processus générique de saisie du journal de révision (seize lignes réparties sur cinq voies) dans lequel l'élément qui se déplace dans le processus est l'entrée du journal elle-même, et non le document. Une demande ouvre une entrée en attente, un auteur implémente la modification et dépose une description avant et après, un réviseur compare cette description à la modification réelle avant de fermer quoi que ce soit, et un auditeur échantillonne les entrées fermées plus tard. Cette étape de comparaison est ce qu'une feuille de calcul créée à la main n'a presque jamais, car personne n'a pour tâche explicite de l'exécuter. QueryChart remplace entièrement le tableau construit à la main : chaque modification d'un graphique est capturée dans un journal des modifications avec les valeurs avant/après par champ et le nom de l'éditeur, visible dans un écran de comparaison des versions, dans /features/version-control ; personne n'a besoin de saisir l'entrée, car il s'agit d'un enregistrement de ce qui a été réellement modifié, et non d'une auto-évaluation.

Comment cela fonctionne

1. Séparez le journal du document

   Mettez l'historique des révisions dans son propre artefact (un tableau sur la page de garde ou un registre autonome), jamais sous la forme d'un paragraphe enfoui dans le corps. Le document change ; le journal est le seul des deux qui ne peut que croître.

2. Corrigez les colonnes avant la première entrée

   Numéro de version, date, auteur, une description claire de ce qui a changé et pourquoi, une référence à la version qu'elle remplace et qui a vérifié l'entrée. Oubliez l'un ou l'autre des deux derniers et il n'y a aucun moyen de distinguer un enregistrement vérifié de l'auto-évaluation d'un auteur.

3. Ouvrez l'entrée avant la modification, pas après

   Enregistrez une entrée en attente (numéro, lien vers le document, auteur attribué) dès qu'une modification est approuvée, avant que quiconque n'ouvre le fichier. Une entrée écrite après coup est reconstruite à partir de la mémoire, ce qui correspond exactement au mode de défaillance qu'un journal vise à empêcher.

4. Écrivez ce qui a changé, pas que quelque chose a changé

   La « Section 4 mise à jour » n'est pas une description ; "a changé le seuil d'approbation de 500 $ à 2 000 $ dans l'article 4". Enregistrez l'avant et l'après en termes simples, le nom de l'auteur et la date, afin qu'un lecteur puisse reconstituer le changement sans ouvrir le propre historique du document.

5. Vérifiez l'entrée par rapport à la modification réelle

   Demandez à quelqu'un d'autre que l'auteur de comparer la description enregistrée à ce qui a réellement changé dans le document avant la fermeture de l'entrée. S'ils ne sont pas d'accord, déterminez si le document ou l'entrée est erroné : corriger l'entrée n'est pas toujours un retour en arrière pour l'auteur.

6. Exemples d'entrées fermées, ne les examinez pas toutes

   Créez un audit périodique qui vérifie un échantillon d'entrées clôturées par rapport à leurs documents, selon un calendrier qui appartient au programme d'audit plutôt qu'un contrôle ad hoc. C’est ce qui fait du journal quelque chose auquel vous pouvez faire confiance sans le revérifier vous-même.

Erreurs à éviter

• Le journal comme test de mémoire

  L'écriture de l'entrée quelques jours après la modification transforme un enregistrement en une reconstruction. Ouvrez l'entrée en attente lorsque la modification est approuvée et déposez la description avant et après le jour même de la modification, et non à partir de ce dont quelqu'un se souvient des semaines plus tard.

• Modification de l'historique en place

  Corriger la troisième ligne d'une feuille de calcul pour corriger une mauvaise description détruit ce à quoi sert précisément un historique de révision : la preuve de ce qui a été enregistré et à quel moment. Ajoutez plutôt une nouvelle ligne ; /fr/guides/comment-suivre-les-modifications-dans-une-sop et /fr/guides/comment-gerer-les-revisions-des-sop couvrent spécifiquement cette discipline d'ajout uniquement pour les SOP.

• Un journal que personne ne vérifie par rapport au document

  Une table avec une colonne Version et Description mais aucune étape de vérification est un ensemble de revendications, pas un enregistrement. Donnez à la comparaison sa propre ligne avec son propre propriétaire, comme le fait « Comparer l'entrée du journal avec la modification implémentée » dans le tableau ci-dessus, ou le journal est aussi fiable que la mémoire de l'auteur.

• Confondre le journal avec le processus qui le produit

  Un historique des révisions enregistre ce qui a changé ; il ne décide pas qui peut approuver une modification ni où se trouvent les copies remplacées : il s'agit du contrôle des documents, entièrement couvert par /fr/templates/organigramme-du-processus-de-controle-des-documents. Construisez les deux, mais conservez-les comme des artefacts distincts.

Questions fréquentes

Quelle est la différence entre un historique des révisions et un contrôle de version ?

Un historique des révisions est l'artefact : le tableau de la version, de la date, de l'auteur, de la description et du vérificateur. Le contrôle de version est la pratique qui maintient ce tableau honnête : la règle selon laquelle rien n'est édité sans entrée, que les entrées ne sont jamais réécrites après coup et que quelqu'un d'autre que l'auteur vérifie les unes par rapport aux autres. Vous pouvez avoir un historique des révisions avec un contrôle de version faible derrière : la table existe, mais personne ne vérifie jamais une ligne par rapport à la véritable modification.

De quelles colonnes une table d'historique des révisions a-t-elle besoin ?

Numéro de version, date, auteur, une description claire de ce qui a changé et pourquoi, une référence à la version qu'elle remplace et, le plus ignoré des tableaux construits à la main, qui a vérifié l'entrée par rapport à la modification réelle. Une ligne manquant la dernière colonne est une auto-évaluation de l'auteur et non un enregistrement vérifié.

Un historique des révisions doit-il être modifié pour corriger une erreur dans une ancienne entrée ?

Non. Ajoutez une nouvelle ligne qui corrige l’enregistrement plutôt que de réécrire l’ancien ; le journal est aussi fiable que son historique d'ajout uniquement est intact. Si la mauvaise chose était le document plutôt que l'entrée, le correctif appartient à une nouvelle révision du document, et non à une ligne de journal réécrite.

Une feuille de calcul entretenue à la main est-elle suffisante pour un historique des révisions, ou ai-je besoin d'un logiciel ?

Une feuille de calcul fonctionne jusqu'à ce que quelqu'un modifie une ligne au lieu d'en ajouter une, ce qui est difficile à éviter et facile à manquer. L'historique des versions de QueryChart écrit automatiquement le journal équivalent : un journal des modifications avec les valeurs avant/après par champ et le nom de l'éditeur pour chaque révision, visible dans un écran de comparaison des versions et restaurable à tout moment, dans /features/version-control. Le tableau ci-dessus montre la version manuelle d'une même discipline (une requête, une description déposée, une étape de vérification) quel que soit l'outil qui l'exécute.