Como atualizar a documentação automaticamente a cada lançamento

Atualizado em 3 de novembro de 2026

Para atualizar a documentação automaticamente a cada lançamento, inicie uma tarefa de documentação a partir do próprio lançamento: um release publicado no GitHub, um evento de release no GitLab, uma tag no Bitbucket ou uma nova entrada no seu changelog público. A tarefa lê as notas de lançamento, encontra as páginas de ajuda e vídeos afetados pelo lançamento, rascunha as alterações e as envia para uma pessoa aprovar. Para documentação voltada ao cliente, essa etapa de revisão é o que mantém a automação da documentação segura.

Este guia percorre esse pipeline primeiro com qualquer ferramenta (GitHub Actions, GitLab, Bitbucket, página de changelog) e, em seguida, mostra como o Autopilot da Clevera executa o mesmo ciclo para uma central de ajuda com vídeos.

O que é documentação contínua?#

A Swimm, que popularizou o termo, define documentação contínua como a criação e atualização incremental de documentação como parte do fluxo de trabalho de desenvolvimento, em vez de projetos ocasionais de atualização. A maioria das ferramentas criadas com essa ideia, agora frequentemente vendidas como "documentação que se autoatualiza", monitora commits ou pull requests e atualiza a documentação do desenvolvedor ao lado do código.

Centrais de ajuda voltadas ao cliente precisam de um gatilho diferente. Os leitores não veem um commit; eles veem um lançamento. A tabela mostra o equilíbrio necessário.

O argumento a favor da automação é a velocidade. A pesquisa State of DevOps de 2021 da DORA descobriu que equipes de elite fazem deploy 973 vezes mais frequentemente do que as de baixo desempenho. Nem todo deploy altera o que os leitores veem, mas as equipes enviam atualizações com muito mais frequência do que qualquer um consegue revisar artigos manualmente. A mesma pesquisa descobriu que equipes com documentação de alta qualidade tinham 3,8 vezes mais chances de implementar as melhores práticas de segurança, portanto, a documentação não é um detalhe secundário. E documentação desatualizada é comum: na Pesquisa de Código Aberto de 2017 do GitHub, 93% dos entrevistados encontraram documentação incompleta ou desatualizada, e 60% dos colaboradores disseram que raramente ou nunca contribuem para a documentação.

Passo 1: Escreva notas de lançamento que uma tarefa de documentação possa usar#

A automação só pode atualizar a documentação tão bem quanto as notas de lançamento descrevem a alteração. Duas convenções ajudam.

• Agrupe as alterações por tipo. O Keep a Changelog usa Added, Changed, Deprecated, Removed, Fixed e Security. "Added" geralmente significa um novo artigo ou vídeo; "Changed" e "Removed" significam que o conteúdo existente agora está incorreto.
• Separe o que os usuários veem do que eles não veem. As notas de lançamento geradas automaticamente do GitHub classificam pull requests mesclados por rótulo em .github/release.yml e podem excluir rótulos inteiramente.

# .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: ["*"]

Um rótulo "ui-change" é o mais útil para adicionar: ele informa à tarefa de documentação quais itens podem quebrar um artigo. Nomeie a tela no título do pull request também ("Configurações de faturamento: mover lembretes para Automações"), para que a alteração possa ser correspondida às páginas que mostram essa tela.

Passo 2: Atualize a documentação automaticamente no lançamento: inicie uma tarefa#

Todo grande host Git pode iniciar uma tarefa quando você envia um lançamento, que é como você gera atualizações de documentação a partir de releases do GitHub ou seus equivalentes no GitLab e Bitbucket. Os detalhes diferem.

No GitHub, um workflow mínimo parece com isto:

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

Use published em vez de created: de acordo com a referência de eventos do GitHub, created não dispara para rascunhos de release, enquanto published cobre tanto releases estáveis quanto pré-releases. Passe as notas de lançamento através de uma variável de ambiente como acima, não diretamente no comando do shell, porque o texto do release é entrada do usuário. E se uma ferramenta como release-please ou semantic-release criar seus releases com o token padrão, eventos que ela dispara não iniciarão seu workflow de documentação; forneça a essa ferramenta um token de GitHub App ou um token de acesso pessoal.

No GitLab e Bitbucket, o equivalente é uma tarefa que roda em 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"

Passo 3: Encontre as páginas e vídeos que cada lançamento afeta#

Este é o passo que a maioria dos guias pula, e o que decide se a automação ajuda. Uma nota de lançamento diz "Lembretes movidos para Faturamento → Automações"; sua tarefa tem que transformar isso em "estes três artigos e dois vídeos agora estão incorretos".

Três métodos, do mais simples ao mais robusto:

1. Pesquise por rótulos renomeados. Extraia todas as strings de UI citadas das notas de lançamento e pesquise nos seus artigos e roteiros de vídeo pela redação antiga.
2. Mantenha um inventário de telas. Marque cada artigo e vídeo com as telas que ele mostra e combine os nomes das telas nos títulos dos pull requests com ele. Nosso guia sobre manter a documentação atualizada tem um modelo de inventário.
3. Deixe um modelo ler cada candidato na íntegra. Dê a um modelo de linguagem as notas de lançamento e o texto completo (ou transcrição) de cada página candidata, e peça um veredito: ainda correto, precisa de uma correção de texto ou precisa de novas capturas de tela ou filmagens. Ler a página inteira é importante, porque o passo quebrado geralmente não é o que a nota de lançamento menciona.

Um prompt para esse veredito pode ser curto:

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.

Passo 4: Rascunhe as atualizações#

Para texto, o rascunho é a parte fácil: o modelo recebe as notas de lançamento, o artigo atual e suas regras de estilo, e retorna uma versão revisada. Mantenha o ID e a URL do artigo, para que você atualize a página existente em vez de criar um quase duplicado, e registre qual lançamento a alterou pela última vez. As regras em como escrever artigos para a central de ajuda compõem um bom prompt de estilo.

Capturas de tela e vídeos são mais difíceis. Um modelo não pode produzir uma captura de tela de uma tela que ele não viu. Você captura novas imagens em sua suíte de testes de UI, regrava o fluxo alterado ou marca o item para uma pessoa regravar. Marque cada item no plano: correção de texto, nova captura de tela ou regravar. Uma vez que o fluxo alterado é gravado, transformar a gravação em documentação lhe dá novos passos e capturas de tela de uma só vez.

Passo 5: Coloque uma pessoa entre o rascunho e o leitor#

Descrições de pull requests são escritas por muitas pessoas e nunca revisadas com os clientes em mente. Trate-as, e as notas de lançamento, como entrada não confiável: elas podem conter instruções que um modelo seguirá. Envie cada rascunho para revisão.

• Quem aprova: o líder de suporte ou documentação para conteúdo da central de ajuda, um engenheiro para referência de API.
• O que uma boa revisão mostra: cada página afetada com um diff de antes e depois, o item de lançamento que causou isso e uma lista clara de "nada a alterar" para que os revisores confiem no que foi pulado.
• O que publicar automaticamente: nada voltado ao cliente no início. Assim que alguns lançamentos passarem sem surpresas, você pode flexibilizar a regra para itens de baixo risco, como correções de texto de nível de digitação.

Qual configuração se adapta à sua equipe?#

Se sua equipe já trabalha no Claude Code, você também pode pedir que ele atualize a documentação após uma release via MCP; explicamos como fazer isso em como atualizar docs com o Claude Code após cada release.

Como atualizar automaticamente a documentação no lançamento com o Clevera Autopilot#

Clevera é uma plataforma de IA que transforma uma gravação de tela em um vídeo de instruções narrado, um artigo de ajuda passo a passo e uma página na sua central de ajuda hospedada, em 74 idiomas. Seu recurso Autopilot, nos planos Pro e Custom, executa as etapas 2 a 5 acima para uma central de ajuda Clevera.

• Gatilho. A receita Manter minha central de ajuda atualizada quando lançarmos algo monitora as Releases ou Mudanças mescladas de um repositório, ou uma Página de changelog lida diariamente ou semanalmente. O GitHub se conecta por meio de um aplicativo somente leitura; GitLab (gitlab.com) e Bitbucket Cloud se conectam da mesma forma onde disponível. O Clevera verifica o repositório cerca de uma vez por hora. Ele lê notas de release, tags e títulos e descrições de pull requests, nunca o seu código.
• Correspondência. Cada execução verifica até 40 vídeos e artigos da central de ajuda e lê cada um dos afetados na íntegra.
• Rascunho. Cada item recebe um veredito: ainda correto, uma correção de texto mostrada antes e depois, ou gravar novamente com os novos passos. A nova gravação requer Usar meu app: o endereço do seu app e, se necessário, um login (uma conta de teste funciona melhor). O novo vídeo substitui o antigo no mesmo link, então, assim como nas edições do LiveSync, incorporações e páginas da central de ajuda o exibem sem novos links.
• Revisão. Cada execução aguarda você. Você desmarca o que não deseja e clica em Executar, ou clica em Pedir alterações para um novo plano. Um plano expira após sete dias, e a próxima execução captura tudo o que aconteceu desde então.

Monitorar e planejar é gratuito; cada linha de um plano mostra seus créditos, e uma execução típica custa de 10 a 150 créditos. O mesmo ciclo está disponível para vídeos sem uma central de ajuda através de Atualizar meus vídeos quando o produto mudar, e Gravar um vídeo para cada novo recurso propõe um novo tutorial para o que cada release adiciona (veja como fazer um vídeo de notas de release para a versão manual).

Onde o Clevera não é a ferramenta certa: ele não gera referência de API a partir do código nem escreve seu CHANGELOG.md. Para esse lado, veja nossa comparação de geradores de changelog por IA, ou servidores MCP para documentação se você quiser um agente de IA para editar docs em outra plataforma.

Começar gratuitamente para criar a central de ajuda e os vídeos primeiro; o Autopilot vem com o plano Pro. As etapas de configuração estão no artigo de ajuda Conectar o GitHub ou outro repositório ao Autopilot.

FAQ#

A documentação pode se atualizar automaticamente quando lançamos uma versão?#

A detecção e a criação de rascunhos podem ser automáticas: uma release inicia um job que encontra as páginas afetadas e redige as correções. A publicação deve continuar sendo uma decisão humana para docs voltados ao cliente, porque as notas de release nem sempre dizem o que você pretendia que os leitores fizessem.

Os docs devem ser atualizados a cada commit ou a cada release?#

Para centrais de ajuda, a cada release. Commits e pull requests mudam constantemente e muitas vezes ficam atrás de feature flags; uma release é quando os leitores realmente veem a mudança. Docs de desenvolvedor que ficam junto ao código podem seguir os pull requests.

Como aciono uma GitHub Action quando uma release é publicada?#

Use on: release com types: [published]. Se a release for criada por outro workflow usando o GITHUB_TOKEN padrão, ele não iniciará seu workflow; use um token de GitHub App ou um personal access token para a ferramenta de release.

E se não publicarmos releases no GitHub?#

Use o sinal que você tem: eventos de release do GitLab, pipelines de tag do Bitbucket ou um job agendado que lê sua página pública de changelog ou seu feed RSS. O Autopilot do Clevera pode monitorar uma página de changelog diariamente ou semanalmente exatamente para este caso.

Capturas de tela e vídeos também podem ser atualizados automaticamente?#

Capturas de tela podem ser feitas em testes de UI a cada build. Vídeos precisam que o fluxo alterado seja gravado novamente; um gravador de IA pode reexecutar uma instrução salva na nova UI, e o Autopilot pode fazer isso para vídeos do Clevera quando você fornece o endereço do seu app (e um login, se o seu app precisar). Assista à nova gravação antes de aprová-la.