Manutenção de Documentação

Mantenha a documentação honesta com o mínimo de alterações. O objetivo é o alinhamento entre a documentação e o comportamento, não reescritas estilísticas ou reorganizações cosméticas. Os revisores devem ser capazes de ler um diff e ver "isso atualiza a documentação para corresponder a mudanças recentes de comportamento".

Quando usar

• Um PR ou um conjunto recente de merges mudou o comportamento visível para o usuário: flags de CLI, formatos de API, valores padrão, chaves de configuração, endpoints, variáveis de ambiente, versões suportadas.
• Um bug reportado pelo usuário rastreado até documentação desatualizada.
• Uma versão está sendo cortada e a documentação precisa de uma revisão contra os commits mesclados.
• Um novo recurso foi lançado, mas apenas a descrição do PR do engenheiro descreve como usá-lo.

Quando não usar

• A mudança é apenas interna (renomeação de helper privado, refatoração) sem impacto visível para o usuário.
• Você quer "melhorar a documentação" sem uma âncora de comportamento. Isso é um projeto separado e com escopo definido, não manutenção — faça um plano primeiro.

A revisão

1. Estabeleça a base. Obtenha o intervalo de commits que você está documentando (desde a última tag de release, desde o último commit de documentação mesclado, ou desde um PR específico).
2. Enumere as mudanças visíveis para o usuário. Leia os commits e as descrições dos PRs. Liste, para cada mudança, o que um usuário pode fazer de diferente agora.
3. Mapeie as mudanças para a documentação. Para cada mudança, encontre todas as páginas que mencionam o conceito afetado. Alvos comuns: README, referência de CLI, referência de API, referência de configuração, guia de migração, FAQ, exemplos.
4. Atualize precisamente. Edite apenas as linhas que precisam ser alteradas. Não reembale parágrafos que você não modificou — isso polui o diff.
5. Adicione novas entradas onde necessário. Nova flag de CLI → entrada na referência de CLI. Nova variável de ambiente → entrada na referência de configuração. Novo endpoint → entrada na referência de API. Não adicione apenas ao changelog.
6. Atualize exemplos e trechos de código. Blocos de código na documentação ficam errados mais rápido do que o texto. Reexecute qualquer exemplo que toque em um novo comportamento.
7. Escreva a nota de release. Uma frase por mudança visível para o usuário. Agrupe por Adicionado / Alterado / Corrigido / Depreciado / Removido. Link para os PRs relevantes e a seção de documentação.
8. Verifique cruzado. Procure na documentação por frases do comportamento antigo e remova ou atualize as que ficaram para trás.

Base de estilo

• Voz: segunda pessoa ("você pode passar --json para ..."). Evite "nós" exceto em páginas narrativas.
• Tempo verbal: presente, não futuro. O comportamento existe assim que é lançado.
• Títulos: imperativo ("Configure o cache") ou frase nominal ("Configuração de cache"), combine com a página circundante.
• Blocos de código: inclua a tag de linguagem para que a marcação de sintaxe funcione.
• Links cruzados: link para a primeira menção de um conceito em cada página; não link para todas as ocorrências.
• Evite prometer comportamento futuro. Se algo não foi lançado, marque-o como experimental ou omita-o.

Detecção de desvio

Uma página de documentação está desviada se qualquer um destes for verdadeiro:

• Documenta uma flag, chave ou endpoint que não existe mais.
• Um exemplo não roda como escrito.
• Um valor padrão na documentação não corresponde ao código.
• Uma lista de versões suportadas exclui uma versão que o projeto realmente suporta, ou inclui uma que foi descontinuada.
• Uma seção "Em breve" referencia um recurso que foi lançado ou cancelado.

Quando você encontrar um desvio, corrija-o na mesma revisão e anote-o no grupo Fixed da nota de release.

Regras de notas de release

• Uma frase por item. Se duas frases forem necessárias, o item provavelmente são dois itens.
• Impacto do usuário primeiro, causa interna depois. Faster cold start (avoid full bundle download on first run) é melhor que Refactor bootstrap loader.
• Link para o PR para leitores de engenharia e para a página de documentação para usuários.
• Marque mudanças que quebram compatibilidade explicitamente: prefixo **Breaking:**. Inclua passos de migração inline ou via link.

Antí-padrões

• PRs de documentação massivos que agrupam reescritas estilísticas com atualizações reais. Revisores não conseguem distinguir quais linhas refletem mudanças reais de comportamento.
• Mensagens de commit "Documentação atualizada" sem detalhes. Faça o commit dizer o que mudou e por quê.
• Adicionar ao changelog sem atualizar a documentação de referência para a qual o changelog aponta.
• Marcar um recurso como disponível antes que seu código seja integrado. A documentação deve seguir o comportamento, não prometê-lo.