Come aggiornare automaticamente la documentazione a ogni rilascio

Aggiornato il 3 novembre 2026

Per aggiornare automaticamente la documentazione a ogni rilascio, avvia un job di documentazione dal rilascio stesso: un rilascio GitHub pubblicato, un evento di rilascio GitLab, un tag Bitbucket o una nuova voce nel tuo changelog pubblico. Il job legge le note di rilascio, trova le pagine di aiuto e i video interessati dal rilascio, bozza le modifiche e le invia a una persona per l'approvazione. Per la documentazione rivolta ai clienti, questo passaggio di revisione è ciò che rende sicura l'automazione della documentazione.

Questa guida illustra prima tale pipeline con qualsiasi strumento (GitHub Actions, GitLab, Bitbucket, una pagina di changelog), poi mostra come l'Autopilot di Clevera esegue lo stesso ciclo per un centro assistenza con video.

Cos'è la documentazione continua?#

Swimm, che ha reso popolare il termine, definisce la documentazione continua come la creazione e l'aggiornamento incrementale della documentazione come parte del flusso di lavoro di sviluppo, invece che in progetti di recupero occasionali. La maggior parte degli strumenti basati su questa idea, spesso venduti come "documentazione che si auto-aggiorna", monitora i commit o le pull request e aggiorna la documentazione per sviluppatori accanto al codice.

I centri assistenza rivolti ai clienti necessitano di un trigger diverso. I lettori non vedono un commit; vedono un rilascio. La tabella mostra il compromesso.

La ragione dell'automazione è la velocità. La ricerca State of DevOps 2021 di DORA ha rilevato che i team d'élite distribuiscono 973 volte più frequentemente rispetto ai team con prestazioni inferiori. Non ogni distribuzione cambia ciò che vedono i lettori, ma i team rilasciano molto più spesso di quanto chiunque possa ricontrollare manualmente gli articoli. La stessa ricerca ha rilevato che i team con una documentazione di alta qualità avevano 3,8 volte più probabilità di implementare le migliori pratiche di sicurezza, quindi la documentazione non è un problema secondario. E la documentazione obsoleta è comune: nel sondaggio Open Source 2017 di GitHub, il 93% degli intervistati si è imbattuto in documentazione incompleta o obsoleta, e il 60% dei collaboratori ha affermato di contribuire raramente o mai alla documentazione.

Passaggio 1: Scrivi note di rilascio che un job di documentazione possa utilizzare#

L'automazione può aggiornare la documentazione solo tanto quanto le note di rilascio descrivono la modifica. Due convenzioni aiutano.

• Raggruppa le modifiche per tipo. Keep a Changelog utilizza Added, Changed, Deprecated, Removed, Fixed e Security. "Added" solitamente significa un nuovo articolo o video; "Changed" e "Removed" significano che il contenuto esistente è ora errato.
• Separa ciò che gli utenti vedono da ciò che non vedono. Le note di rilascio generate automaticamente di GitHub ordinano le pull request unite per etichetta in .github/release.yml e possono escludere le etichette interamente.

# .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'etichetta "ui-change" è l'etichetta più utile da aggiungere: indica al job di documentazione quali elementi possono invalidare un articolo. Nomina la schermata anche nel titolo della pull request ("Impostazioni di fatturazione: sposta i promemoria in Automazioni"), in modo che la modifica possa essere abbinata alle pagine che mostrano quella schermata.

Passaggio 2: Aggiornamento automatico della documentazione al rilascio: avvia un job#

Ogni principale host Git può avviare un job quando distribuisci, che è il modo in cui generi aggiornamenti della documentazione dai rilasci GitHub o dai loro equivalenti GitLab e Bitbucket. I dettagli differiscono.

Su GitHub, un workflow minimo appare così:

# .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

Usa published invece di created: secondo il riferimento agli eventi di GitHub, created non si attiva per i rilasci in bozza, mentre published copre sia i rilasci stabili che le pre-release. Passa le note di rilascio tramite una variabile d'ambiente come sopra, non direttamente nel comando shell, perché il testo del rilascio è input dell'utente. E se uno strumento come release-please o semantic-release crea i tuoi rilasci con il token predefinito, gli eventi che attiva non avvieranno il tuo workflow di documentazione; dai a quello strumento un token GitHub App o un token di accesso personale.

Su GitLab e Bitbucket, l'equivalente è un job che viene eseguito sui tag:

# .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"

Passaggio 3: Trova le pagine e i video interessati da ogni rilascio#

Questo è il passaggio che la maggior parte delle guide salta, e quello che decide se l'automazione aiuta. Una nota di rilascio dice "Promemoria spostati in Fatturazione → Automazioni"; il tuo job deve trasformarlo in "questi tre articoli e due video sono ora errati".

Tre metodi, dal più semplice al più efficace:

1. Cerca etichette rinominate. Estrai ogni stringa dell'interfaccia utente tra virgolette dalle note di rilascio e cerca nei tuoi articoli e script video la vecchia dicitura.
2. Tieni un inventario delle schermate. Etichetta ogni articolo e video con le schermate che mostra e abbina i nomi delle schermate nei titoli delle pull request. La nostra guida su come mantenere aggiornata la documentazione ha un modello di inventario.
3. Lascia che un modello legga ogni candidato per intero. Dai a un modello linguistico le note di rilascio e il testo completo (o la trascrizione) di ogni pagina candidata, e chiedi un verdetto: ancora corretto, necessita di una correzione del testo, o necessita di nuovi screenshot o filmati. Leggere l'intera pagina è importante, perché il passaggio errato spesso non è quello indicato nella nota di rilascio.

Un prompt per quel verdetto può essere breve:

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.

Passaggio 4: Bozza gli aggiornamenti#

Per il testo, la bozza è la parte facile: il modello riceve le note di rilascio, l'articolo corrente e le tue regole di stile, e restituisce una versione revisionata. Mantieni l'ID e l'URL dell'articolo, in modo da aggiornare la pagina esistente invece di crearne una quasi duplicata, e registra quale rilascio l'ha modificata per l'ultima volta. Le regole in come scrivere articoli per il centro assistenza costituiscono un buon prompt di stile.

Screenshot e video sono più difficili. Un modello non può produrre uno screenshot di una schermata che non ha visto. Puoi acquisire nuove immagini nella tua suite di test dell'interfaccia utente, registrare nuovamente il flusso modificato o contrassegnare l'elemento affinché una persona lo registri di nuovo. Contrassegna ogni elemento nel piano: correzione del testo, nuovo screenshot o nuova registrazione. Una volta registrato il flusso modificato, trasformare la registrazione in documentazione ti fornisce nuovi passaggi e screenshot in un unico passaggio.

Passaggio 5: Metti una persona tra la bozza e il lettore#

Le descrizioni delle pull request sono scritte da molte persone e mai revisionate pensando ai clienti. Trattale, e le note di rilascio, come input non attendibili: possono contenere istruzioni che un modello seguirà. Invia ogni bozza a revisione.

• Chi approva: il responsabile dell'assistenza o della documentazione per i contenuti del centro assistenza, un ingegnere per il riferimento API.
• Cosa mostra una buona revisione: ogni pagina interessata con un confronto prima-dopo, l'elemento di rilascio che l'ha causato e un chiaro elenco di "nulla da cambiare" affinché i revisori si fidino di ciò che è stato saltato.
• Cosa pubblicare automaticamente: nulla rivolto ai clienti all'inizio. Una volta che alcuni rilasci sono passati senza sorprese, puoi allentare la regola per elementi a basso rischio come correzioni di testo a livello di refuso.

Quale configurazione si adatta al tuo team?#

Se il tuo team lavora già in Claude Code, puoi anche chiedergli di aggiornare la documentazione dopo un rilascio tramite MCP; ne parliamo in come aggiornare la documentazione con Claude Code dopo ogni rilascio.

Come aggiornare automaticamente la documentazione al rilascio con Clevera Autopilot#

Clevera è una piattaforma AI che trasforma una registrazione dello schermo in un video tutorial narrato, un articolo di supporto passo-passo e una pagina nel tuo centro assistenza ospitato, in 74 lingue. La sua funzione Autopilot, inclusa nei piani Pro e Custom, esegue i passaggi da 2 a 5 sopra indicati per un centro assistenza Clevera.

• Trigger. La ricetta Mantieni aggiornato il mio centro assistenza quando rilasciamo monitora i Rilasci o le Modifiche unite di un repository, oppure una Pagina del changelog letta quotidianamente o settimanalmente. GitHub si connette tramite un'app in sola lettura; GitLab (gitlab.com) e Bitbucket Cloud si connettono allo stesso modo dove disponibile. Clevera controlla il repository circa una volta all'ora. Legge note di rilascio, tag e titoli e descrizioni delle pull request, mai il tuo codice.
• Corrispondenza. Ogni esecuzione controlla fino a 40 video e articoli del centro assistenza e legge interamente ciascuno di quelli interessati.
• Bozza. Ogni elemento riceve un verdetto: ancora corretto, una correzione del testo mostrata prima e dopo, o registra di nuovo con i nuovi passaggi. La ri-registrazione richiede Usa la mia app: l'indirizzo della tua app e, se necessario, un accesso (un account di test funziona meglio). Il nuovo video sostituisce quello vecchio allo stesso link, quindi, come per le modifiche LiveSync, gli embed e le pagine del centro assistenza lo mostrano senza nuovi link.
• Revisione. Ogni esecuzione attende te. Deselezioni ciò che non vuoi e clicchi su Esegui, oppure clicchi su Chiedi modifiche per un nuovo piano. Un piano scade dopo sette giorni e l'esecuzione successiva riprende tutto ciò che è avvenuto nel frattempo.

Il monitoraggio e la pianificazione sono gratuiti; ogni riga di un piano mostra i relativi crediti e un'esecuzione tipica costa da 10 a 150 crediti. Lo stesso ciclo è disponibile per i video senza un centro assistenza tramite Aggiorna i miei video quando il prodotto cambia, e Registra un video per ogni nuova funzionalità propone un nuovo tutorial per ciò che ogni rilascio aggiunge (vedi come creare un video per le note di rilascio per la versione manuale).

Dove Clevera non è lo strumento giusto: non genera riferimenti API dal codice né scrive il tuo CHANGELOG.md. Per questo aspetto, vedi il nostro confronto tra generatori di changelog AI, o server MCP per la documentazione se desideri che un agente AI modifichi la documentazione in un'altra piattaforma.

Inizia gratis per creare prima il centro assistenza e i video; Autopilot è incluso in Pro. I passaggi di configurazione sono nell'articolo di supporto Connetti GitHub o un altro repository ad Autopilot.

FAQ#

La documentazione può aggiornarsi automaticamente quando rilasciamo?#

Il rilevamento e la stesura possono essere automatici: un rilascio avvia un job che trova le pagine interessate e redige le correzioni. La pubblicazione dovrebbe rimanere una decisione umana per la documentazione rivolta ai clienti, perché le note di rilascio non sempre indicano ciò che intendevi far fare ai lettori.

La documentazione dovrebbe aggiornarsi a ogni commit o a ogni rilascio?#

Per i centri assistenza, a ogni rilascio. I commit e le pull request cambiano costantemente e spesso si trovano dietro feature flag; un rilascio è il momento in cui i lettori vedono effettivamente il cambiamento. La documentazione per sviluppatori che vive accanto al codice può seguire le pull request.

Come attivo un GitHub Action quando viene pubblicato un rilascio?#

Usa on: release con types: [published]. Se il rilascio viene creato da un altro workflow utilizzando il GITHUB_TOKEN predefinito, non avvierà il tuo workflow; usa un token GitHub App o un token di accesso personale per lo strumento di rilascio.

Cosa succede se non pubblichiamo i rilasci su GitHub?#

Usa il segnale che hai a disposizione: eventi di rilascio GitLab, pipeline di tag Bitbucket o un job pianificato che legge la tua pagina pubblica del changelog o il suo feed RSS. Autopilot di Clevera può monitorare una pagina del changelog quotidianamente o settimanalmente proprio per questo caso.

Anche screenshot e video possono essere aggiornati automaticamente?#

Gli screenshot possono essere acquisiti nei test dell'interfaccia utente a ogni build. I video richiedono che il flusso modificato venga registrato di nuovo; un registratore AI può rieseguire un'istruzione salvata sulla nuova interfaccia utente e Autopilot può farlo per i video di Clevera quando gli fornisci l'indirizzo della tua app (e un accesso se la tua app ne richiede uno). Guarda la nuova ripresa prima di approvarla.