Como escrever release notes que as pessoas realmente leem

Para escrever release notes que as pessoas leem, responda uma pergunta por entrada: o que o leitor pode fazer agora que antes não podia, e o que ele precisa fazer a respeito. Coloque qualquer coisa com prazo em primeiro lugar, nomeie quem é afetado, diga “nenhuma ação necessária” quando for verdade, e pule releases que não têm nada a dizer. Tudo mais nesta página é essa regra aplicada.

Correções de bugs e melhorias de desempenho.

Todo produto já publicou isso uma vez. A causa raramente é preguiça: isso é o que se obtém quando release notes são escritas de dentro, por alguém que passou duas semanas no diff e não consegue mais ver quais partes importariam para um estranho. Um tom melhor não vai resolver isso; responder à pergunta, sim.

O que release notes deveriam incluir?

Release notes deveriam incluir, para cada mudança que merece menção: o que o leitor pode fazer agora, quem é afetado, o que ele deve fazer a respeito (incluindo “nada”), e quando qualquer coisa com prazo entra em vigor. Não deveriam incluir números de tickets internos, nomes de componentes que só a equipe usa, ou um número de versão como único título.

A separação entre uma release note e uma entrada de changelog é o que torna essa lista possível: o changelog guarda tudo, então as notas podem deixar coisas de fora. Exemplos comentados de cada tipo de entrada estão reunidos em exemplos de release notes.

A pergunta que cada entrada responde

O que o leitor pode fazer agora que antes não podia, e o que ele precisa fazer a respeito?

Se uma entrada não consegue responder isso, ela pertence ao changelog e não às release notes. As duas metades importam. A primeira metade é o valor. A segunda metade é a que as equipes esquecem, e é a que gera tickets de suporte quando falta.

Dois exemplos da segunda metade fazendo trabalho de verdade:

• “Webhooks existentes continuam funcionando até 1º de novembro. Depois dessa data, payloads sem assinatura serão rejeitados.”
• “Nenhuma ação necessária. Exports existentes são recodificados automaticamente na próxima vez que você os abrir.”

O segundo diz “nenhuma ação necessária” explicitamente. Essa frase vale a pena escrever toda vez, porque um leitor que não a encontra assume o pior.

Como release notes deveriam ser ordenadas?

Ordene-as por consequência para o leitor, nunca pela parte do sistema que mudou. Agrupar por API, painel, mobile e infraestrutura é o organograma de vocês, não o problema do leitor.

1. Mudanças que quebram algo e qualquer coisa com prazo. Sempre em primeiro, mesmo que seja pequeno. Se um leitor para de ler depois de uma linha, essa é a linha que ele precisava ter lido. Se o prazo é um sunset, a entrada deveria soar como um aviso de depreciação.
2. O que é novo e que eles vão querer. Um por parágrafo, com o resultado na primeira frase.
3. O que melhorou. Bugs que foram relatados, limites que foram elevados, coisas que estavam lentas.
4. Tudo mais, como lista. Atualizações de dependências, refatorações internas, texto menor. Uma linha cada. Ninguém lê essa seção, e ainda assim ela precisa estar lá, porque quem a procura realmente precisa dela.

A reescrita

Antes:

v4.2.0 Corrigido um problema em que o endpoint POST /exports retornava 500 intermitentemente sob carga. Refatorado o worker de export. Atualizado node-pg para 8.11. Melhorado o tratamento de erros no serializador CSV.

Depois:

Exports não falham mais em contas grandes. Contas com mais de aproximadamente 50.000 linhas podiam receber um 500 ao iniciar um export, mais frequentemente no fim do mês. Isso foi corrigido, e exports de qualquer tamanho agora tentam novamente sozinhos em vez de falhar. Nenhuma ação necessária, e qualquer export que falhou na última semana pode simplesmente ser executado novamente.

Também na 4.2.0: node-pg 8.11, erros mais claros no serializador CSV.

Mesma release. A segunda nomeia a conta afetada, o momento em que foi pior, o que mudou, e o que fazer. A atualização de dependência não desapareceu, só deixou de ser o título. O artigo melhores práticas de release notes tem o resto das regras que essa reescrita segue, cada uma com o custo de pulá-la.

Coisas que vale a pena eliminar

• “Estamos animados em anunciar.” O leitor ainda não está animado. Conquiste isso na próxima frase.
• Números de tickets internos. PROJ-4471 não significa nada fora do tracker de vocês. Se a entrada precisa de uma referência, linke a página de docs.
• Nomes de componentes que só a equipe de vocês usa. Se vocês renomearam o “pipeline de ingestão”, digam “importações”.
• Um número de versão como único título. v4.2.0 é um rótulo de arquivamento, não um resumo.
• Screenshots de uma página de configurações que ninguém jamais visitou. Mostre o que mudou, em uso.

Com que frequência release notes deveriam ser publicadas?

Publique quando algo aconteceu, não em um cronograma. Notas que chegam a cada release ensinam todo mundo a ignorá-las. Notas que chegam quando algo aconteceu são abertas. Está tudo bem, e geralmente é correto, lançar uma release sem nenhuma nota e deixar suas entradas rolarem para o próximo conjunto que tenha um título que valha a pena ler.

O changelog continua registrando tudo. Essa é a divisão de trabalho: o changelog é completo, as notas são seletivas. Se vocês mantiverem o changelog estruturado ao longo do caminho, escrever as notas se torna seleção e reescrita em vez de arqueologia.

O template de release notes é a forma que usamos para a etapa de seleção, e exemplos de changelog reúne entradas de equipes cujo changelog é bom o suficiente para derivar notas dele.

Tudo isso assume uma página que você controla totalmente, sem limite de tamanho e com links que funcionam. Release notes para apps mobile cobre o que muda quando a superfície é uma listagem de App Store ou Play Store. Release notes de emergência cobre a outra exceção: o que muda quando não sobra tempo nenhum para seguir o processo normal de escrita.

Um teste antes de publicar

Leia as notas como alguém que esteve de férias por duas semanas e tem 40 segundos. Se, nesse tempo, essa pessoa não conseguir dizer se algo é exigido dela, as notas não estão prontas, por mais precisas que sejam.

FAQ

Quanto tempo release notes deveriam ter? O tempo que as mudanças com consequências exigirem, e nem uma linha a mais. Uma release com uma mudança que quebra algo e duas melhorias são três parágrafos. Encher uma release tranquila para parecer substancial é como os leitores aprendem a pular as notas.

Quem deveria escrever release notes? A pessoa que entende a mudança, editada por alguém que não entende. A engenheira sabe o que mudou; a editora sabe o que um estranho vai entender errado. Escrever a entrada no momento do merge, enquanto a engenheira ainda se lembra, é a prática que torna isso barato.

Release notes deveriam incluir correções de bugs? Sim, as que alguém relatou ou sofreu. Declare o sintoma que o leitor viu, não a causa. “Exports com mais de 50.000 linhas falhavam” é uma correção que um leitor reconhece; “corrigida uma race condition no worker de export” é uma mensagem de commit.

Qual é a diferença entre release notes e um changelog? O changelog é o registro completo e contínuo; as release notes são a mensagem selecionada sobre uma release, escrita para pessoas que ainda não decidiram se isso as interessa. A resposta mais longa está em changelog vs release notes.

As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.

Relacionado na changeloop: Modelo de notas de versão, Exemplos de changelog