Comment mettre à jour automatiquement la documentation à chaque version

Mis à jour le 3 novembre 2026

Pour mettre à jour automatiquement la documentation à chaque version, lancez une tâche de documentation à partir de la version elle-même : une release GitHub publiée, un événement de release GitLab, un tag Bitbucket ou une nouvelle entrée sur votre changelog public. La tâche lit les notes de version, trouve les pages d'aide et les vidéos affectées par la version, rédige les modifications et les envoie à une personne pour approbation. Pour la documentation destinée aux clients, cette étape de révision est ce qui garantit la sécurité de l'automatisation.

Ce guide détaille ce pipeline avec n'importe quel outil (GitHub Actions, GitLab, Bitbucket, page de changelog), puis montre comment l'Autopilot de Clevera exécute la même boucle pour un centre d'aide avec des vidéos.

Qu'est-ce que la documentation continue ?#

Swimm, qui a popularisé le terme, définit la documentation continue comme la création et la mise à jour incrémentale de la documentation dans le cadre du flux de travail de développement, plutôt que lors de projets de rattrapage occasionnels. La plupart des outils basés sur cette idée, désormais souvent vendus comme de la "documentation auto-mise à jour", surveillent les commits ou les pull requests et mettent à jour la documentation développeur à côté du code.

Les centres d'aide destinés aux clients nécessitent un déclencheur différent. Les lecteurs ne voient pas un commit ; ils voient une version. Le tableau montre le compromis.

L'argument en faveur de l'automatisation est la vitesse. La recherche State of DevOps 2021 de DORA a révélé que les équipes d'élite déploient 973 fois plus fréquemment que les moins performantes. Chaque déploiement ne modifie pas ce que voient les lecteurs, mais les équipes publient bien plus souvent que quiconque ne peut vérifier manuellement les articles. La même recherche a révélé que les équipes disposant d'une documentation de haute qualité étaient 3,8 fois plus susceptibles de mettre en œuvre les meilleures pratiques de sécurité, la documentation n'est donc pas un sujet secondaire. Et la documentation obsolète est courante : dans l'enquête Open Source 2017 de GitHub, 93 % des répondants avaient rencontré une documentation incomplète ou obsolète, et 60 % des contributeurs ont déclaré qu'ils contribuaient rarement ou jamais à la documentation.

Étape 1 : Rédiger des notes de version exploitables par une tâche de documentation#

L'automatisation ne peut mettre à jour la documentation qu'en fonction de la qualité des notes de version. Deux conventions aident.

• Groupez les changements par type. Keep a Changelog utilise Added, Changed, Deprecated, Removed, Fixed et Security. "Added" signifie généralement un nouvel article ou une vidéo ; "Changed" et "Removed" signifient que le contenu existant est désormais erroné.
• Séparez ce que les utilisateurs voient de ce qu'ils ne voient pas. Les notes de version générées automatiquement de GitHub trient les pull requests fusionnées par label dans .github/release.yml, et peuvent exclure complètement certains labels.

# .github/release.yml
changelog:
  exclude:
    labels: [internal, chore]
  categories:
    - title: New
      labels: [feature]
    - title: Changed in the app
      labels: [ui-change]
    - title: Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

Un label "ui-change" est le plus utile à ajouter : il indique à la tâche de documentation quels éléments peuvent rendre un article obsolète. Nommez également l'écran dans le titre de la pull request ("Paramètres de facturation : déplacer les rappels vers Automatisations"), afin que le changement puisse être mis en correspondance avec les pages montrant cet écran.

Étape 2 : Mise à jour automatique de la documentation à la version : lancer une tâche#

Chaque hébergeur Git majeur peut lancer une tâche lors de la publication, ce qui permet de générer des mises à jour de documentation à partir des releases GitHub ou de leurs équivalents GitLab et Bitbucket. Les détails diffèrent.

Sur GitHub, un workflow minimal ressemble à ceci :

# .github/workflows/docs-on-release.yml
name: Docs on release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  draft-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Draft docs updates for this release
        env:
          TAG: ${{ github.event.release.tag_name }}
          NOTES: ${{ github.event.release.body }}
        run: ./scripts/draft-docs-updates.sh

Utilisez published plutôt que created : selon la référence des événements de GitHub, created ne se déclenche pas pour les releases en brouillon, tandis que published couvre à la fois les versions stables et les pré-versions. Passez les notes de version via une variable d'environnement comme ci-dessus, et non directement dans la commande shell, car le texte de la release est une saisie utilisateur. Et si un outil comme release-please ou semantic-release crée vos releases avec le token par défaut, les événements qu'il déclenche ne lanceront pas votre workflow de documentation ; donnez plutôt à cet outil un token GitHub App ou un token d'accès personnel.

Sur GitLab et Bitbucket, l'équivalent est une tâche qui s'exécute sur les tags :

# .gitlab-ci.yml
draft-docs:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./scripts/draft-docs-updates.sh "$CI_COMMIT_TAG"

# bitbucket-pipelines.yml
pipelines:
  tags:
    'v*':
      - step:
          script:
            - ./scripts/draft-docs-updates.sh "$BITBUCKET_TAG"

Étape 3 : Trouver les pages et vidéos affectées par chaque version#

C'est l'étape que la plupart des guides sautent, et celle qui détermine si l'automatisation est utile. Une note de version dit "Rappels déplacés vers Facturation → Automatisations" ; votre tâche doit transformer cela en "ces trois articles et deux vidéos sont désormais erronés".

Trois méthodes, de la plus simple à la plus robuste :

1. Rechercher les labels renommés. Extrayez chaque chaîne d'interface utilisateur entre guillemets des notes de version et recherchez l'ancien libellé dans vos articles et scripts vidéo.
2. Tenir un inventaire des écrans. Taguez chaque article et vidéo avec les écrans qu'ils montrent, et faites correspondre les noms d'écran dans les titres des pull requests. Notre guide pour garder la documentation à jour contient un modèle d'inventaire.
3. Laisser un modèle lire chaque candidat en entier. Donnez à un modèle de langage les notes de version et le texte complet (ou la transcription) de chaque page candidate, et demandez un verdict : toujours correct, nécessite une correction de texte, ou nécessite de nouvelles captures d'écran ou séquences vidéo. Lire toute la page est important, car l'étape cassée n'est souvent pas celle nommée dans la note de version.

Un prompt pour ce verdict peut être court :

You check help articles against a software release.
Release notes: {release_notes}
Article ({url}): {article_text}

Answer in JSON: {"verdict": "still_right" | "text_fix" | "new_screenshots_or_footage",
"reason": "<one sentence quoting the release item>",
"changed_steps": [<step numbers>]}
Only use facts from the release notes. If unsure, answer "text_fix" and say why.

Étape 4 : Rédiger les mises à jour#

Pour le texte, le brouillon est la partie facile : le modèle récupère les notes de version, l'article actuel et vos règles de style, puis renvoie une version révisée. Conservez l'ID et l'URL de l'article afin de mettre à jour la page existante plutôt que de créer un doublon, et enregistrez la dernière version qui l'a modifié. Les règles sur comment rédiger des articles pour un centre d'aide constituent un excellent prompt de style.

Les captures d'écran et les vidéos sont plus complexes. Un modèle ne peut pas produire une capture d'écran d'une interface qu'il n'a pas vue. Vous devez soit capturer de nouvelles images dans votre suite de tests UI, réenregistrer le flux modifié, ou signaler l'élément pour qu'une personne le réenregistre. Marquez chaque élément du plan : correction de texte, nouvelle capture d'écran ou réenregistrement. Une fois le flux modifié enregistré, transformer l'enregistrement en documentation vous permet d'obtenir de nouvelles étapes et captures d'écran en une seule fois.

Étape 5 : Placer un humain entre le brouillon et le lecteur#

Les descriptions de pull requests sont écrites par de nombreuses personnes et jamais revues avec les clients à l'esprit. Traitez-les, ainsi que les notes de version, comme des entrées non fiables : elles peuvent contenir des instructions qu'un modèle suivra. Envoyez chaque brouillon à la révision.

• Qui approuve : le responsable du support ou de la documentation pour le contenu du centre d'aide, un ingénieur pour la référence API.
• Ce qu'une bonne révision montre : chaque page affectée avec un diff avant/après, l'élément de version qui l'a causé, et une liste claire "rien à changer" pour que les réviseurs fassent confiance à ce qui a été ignoré.
• Ce qu'il faut publier automatiquement : rien de destiné aux clients au début. Une fois que quelques versions sont passées sans surprise, vous pouvez assouplir la règle pour les éléments à faible risque comme les corrections de texte de type coquilles.

Quelle configuration convient à votre équipe ?#

Si votre équipe utilise déjà Claude Code, vous pouvez aussi lui demander de mettre à jour la documentation après une release via MCP ; nous détaillons cela dans comment mettre à jour la documentation avec Claude Code après chaque release.

Comment mettre à jour automatiquement la documentation lors d'une release avec Clevera Autopilot#

Clevera est une plateforme IA qui transforme un enregistrement d'écran en vidéo explicative commentée, en article d'aide étape par étape et en page pour votre centre d'aide hébergé, en 74 langues. Sa fonctionnalité Autopilot, incluse dans les plans Pro et Custom, exécute les étapes 2 à 5 ci-dessus pour un centre d'aide Clevera.

• Déclencheur. La recette Maintenir mon centre d'aide à jour lors de nos déploiements surveille les Releases ou Modifications fusionnées d'un dépôt, ou une page de changelog lue quotidiennement ou hebdomadairement. GitHub se connecte via une application en lecture seule ; GitLab (gitlab.com) et Bitbucket Cloud se connectent de la même manière lorsque disponible. Clevera vérifie le dépôt environ une fois par heure. L'outil lit les notes de version, les tags ainsi que les titres et descriptions des pull requests, jamais votre code.
• Correspondance. Chaque exécution vérifie jusqu'à 40 vidéos et articles du centre d'aide et lit intégralement chaque élément impacté.
• Rédaction. Chaque élément reçoit un verdict : toujours à jour, une correction de texte affichée avant/après, ou réenregistrer avec les nouvelles étapes. Le réenregistrement nécessite Utiliser mon application : l'adresse de votre application et, si nécessaire, une connexion (un compte de test fonctionne mieux). La nouvelle vidéo remplace l'ancienne au même lien ; ainsi, comme pour les modifications LiveSync, les intégrations et pages du centre d'aide l'affichent sans nouveaux liens.
• Révision. Chaque exécution attend votre validation. Vous décochez ce que vous ne souhaitez pas et cliquez sur Exécuter, ou cliquez sur Demander des modifications pour un nouveau plan. Un plan expire après sept jours, et la prochaine exécution prend en compte tout ce qui s'est passé depuis.

La surveillance et la planification sont gratuites ; chaque ligne d'un plan affiche ses crédits, et une exécution classique coûte entre 10 et 150 crédits. La même boucle est disponible pour les vidéos sans centre d'aide via Mettre à jour mes vidéos lorsque le produit change, et Enregistrer une vidéo pour chaque nouvelle fonctionnalité propose un nouveau tutoriel pour ce que chaque release ajoute (voir comment créer une vidéo de notes de version pour la version manuelle).

Où Clevera n'est pas l'outil adapté : il ne génère pas de référence API à partir du code et n'écrit pas vos CHANGELOG.md. Pour cet aspect, consultez notre comparatif des générateurs de changelog IA, ou les serveurs MCP pour la documentation si vous souhaitez qu'un agent IA modifie la documentation sur une autre plateforme.

Commencez gratuitement pour créer d'abord le centre d'aide et les vidéos ; Autopilot est inclus avec le plan Pro. Les étapes de configuration se trouvent dans l'article d'aide Connecter GitHub ou un autre dépôt à Autopilot.

FAQ#

La documentation peut-elle se mettre à jour automatiquement lors d'une release ?#

La détection et la rédaction peuvent être automatiques : une release lance un job qui identifie les pages impactées et rédige les corrections. La publication doit rester une décision humaine pour la documentation client, car les notes de version n'indiquent pas toujours ce que vous aviez l'intention de faire faire aux lecteurs.

La documentation doit-elle être mise à jour à chaque commit ou à chaque release ?#

Pour les centres d'aide, à chaque release. Les commits et pull requests changent constamment et sont souvent cachés derrière des feature flags ; une release est le moment où les lecteurs voient réellement le changement. La documentation développeur située à côté du code peut suivre les pull requests.

Comment déclencher une GitHub Action lorsqu'une release est publiée ?#

Utilisez on: release avec types: [published]. Si la release est créée par un autre workflow utilisant le GITHUB_TOKEN par défaut, cela ne lancera pas votre workflow ; utilisez un jeton GitHub App ou un jeton d'accès personnel pour l'outil de release.

Que faire si nous ne publions pas de releases sur GitHub ?#

Utilisez le signal dont vous disposez : événements de release GitLab, pipelines de tags Bitbucket, ou un job planifié qui lit votre page de changelog publique ou son flux RSS. L'Autopilot de Clevera peut surveiller une page de changelog quotidiennement ou hebdomadairement pour ce cas précis.

Les captures d'écran et vidéos peuvent-elles aussi être mises à jour automatiquement ?#

Les captures d'écran peuvent être réalisées lors des tests d'interface à chaque build. Les vidéos nécessitent un réenregistrement du flux modifié ; un enregistreur IA peut rejouer une instruction enregistrée sur la nouvelle interface, et Autopilot peut le faire pour les vidéos Clevera lorsque vous lui fournissez l'adresse de votre application (et une connexion si nécessaire). Visionnez la nouvelle prise avant de l'approuver.