Release notes de emergência sob pressão de tempo real
6 min de leitura
A maioria das release notes é escrita depois que o código está pronto, revisada com calma, e publicada em um cronograma que não tem nada a ver com quão urgentemente alguém precisa lê-la. Releases de emergência, patches de segurança, bugs de perda de dados, correções de instabilidade, viram todas essas condições de cabeça para baixo ao mesmo tempo: a nota precisa existir antes de a maioria das pessoas normalmente começar a escrevê-la, mal recebe revisão, e é lida por uma leitora ansiosa em vez de uma calma. Como escrever release notes cobre o processo normal; isto é sobre o que muda quando não sobra tempo para segui-lo.
Qual é a única coisa que uma release note de emergência precisa acertar, mesmo que mais nada?
Se a leitora precisa fazer algo, dito na primeira frase, sem nenhum enquadramento antes disso. Uma leitora que encontra uma nota disparada por incidente muitas vezes já está preocupada, porque ouviu sobre o problema por uma página de status, um thread de suporte, ou seus próprios usuários, e uma nota que abre com contexto antes do item de ação lê como estar segurando informação exatamente nas circunstâncias em que segurar informação lê pior. “Nenhuma ação necessária, isso corrige uma vulnerabilidade que não exigia dados de usuário para ser explorada” e “Atualize imediatamente: esta release corrige um bug que podia mostrar dados de uma conta para outra” são ambas uma frase, e ambas fazem todo o trabalho que uma leitora ansiosa precisa antes de ler mais qualquer coisa.
A edição normal ainda se aplica quando não há tempo para fazê-la?
O instinto de comprimir sobrevive mesmo quando o processo de vários rascunhos que normalmente o produz não sobrevive. A reescrita descreve cortar um primeiro rascunho verboso até sua essência; sob pressão de tempo, muitas vezes não há primeiro rascunho para cortar, o que significa que a disciplina precisa operar na sua cabeça enquanto você escreve, em vez de como um passo separado depois. A abordagem mais rápida: escreva a frase que você diria em voz alta para alguém perguntando “o que preciso saber”, e pare, porque essa frase costuma ser tanto a mais rápida de produzir quanto a única que uma leitora naquele estado vai de fato processar.
| Release note normal | Release note de emergência |
|---|---|
| Escrita depois do code review, antes da publicação | Frequentemente escrita junto com a correção, antes de uma revisão completa |
| Otimizada para escaneamento rápido em muitas entradas | Otimizada para uma entrada lida isolada, sob estresse |
| Pode deixar detalhes para o changelog vinculado | Precisa colocar o fato mais importante primeiro |
| Enquadramento e contexto são bem-vindos | Enquadramento antes do item de ação lê como enrolação |
Alguma vez está tudo bem publicar uma nota antes de estar realmente certa sobre a causa do problema?
Sim, se a nota for honesta sobre essa incerteza em vez de implicar uma certeza que você não tem. “Fizemos deploy de uma correção para o aumento na taxa de erro no checkout; ainda estamos confirmando a causa raiz e vamos atualizar esta nota” é defensável e compra tempo corretamente; uma nota afirmando uma causa específica que você na verdade não confirmou é o tipo de palpite que as pessoas vão te citar de volta depois se ele se provar errado. A disciplina importante aqui não é a velocidade do diagnóstico, mas nunca deixar a certeza da nota exceder a certeza real do time, porque uma afirmação técnica errada em uma nota de emergência prejudica mais a confiança do que uma ignorância admitida.
Confiante demais, não verificado:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."
Honesto sob pressão de tempo:
"Corrigido: alguns clientes foram cobrados duas vezes
por um único pedido. Interrompemos novas ocorrências e
reembolsamos as contas afetadas em 24 horas.
Investigando a causa raiz."Uma nota de emergência deveria mencionar a causa do problema, ou só que ele foi corrigido?
Diga o que foi corrigido e o que a leitora deveria fazer; guarde a causa raiz para uma nota de acompanhamento, uma vez que ela seja de fato conhecida, não estimada. Uma leitora no meio de um incidente quer exatamente dois fatos, se isso está resolvido e se isso afeta a ela, e uma explicação de causa raiz, mesmo precisa, compete com esses dois fatos por atenção no pior momento possível para perdê-la. Um post-mortem, publicado separadamente uma vez que a investigação esteja completa, é onde a causa raiz pertence; misturar os dois documentos sob pressão de tempo produz uma nota que é escrita mais devagar e lida mais devagar, o oposto do que uma emergência precisa.
O problema de atualizações forçadas de apps mobile também se aplica aqui?
O mesmo princípio se aplica, só que ainda mais comprimido. Release notes para apps mobile cobre atualizações forçadas, onde a nota precisa declarar o motivo e o prazo antes de qualquer outra coisa porque a leitora já está irritada por não ter escolha; uma nota de emergência na web é geralmente opcional para a leitora no sentido de que ela escolhe se age com base nela, mas o mesmo instinto de “declarar a restrição primeiro” se aplica, só que por um motivo diferente: não irritação, urgência.
Como evitar que uma nota de emergência leia como uma confissão de culpa quando não deveria?
Descreva a correção e seu efeito, não o erro, e resista ao impulso de se desculpar em excesso, o que lê como enchimento para uma leitora que quer os dois fatos acima. “Encontramos e corrigimos um bug que afetava algumas exportações” declara o que aconteceu sem adicionar drama a isso; “Lamentamos profundamente por este problema sério que afetou nossos valiosos clientes” atrasa a informação útil por uma frase inteira para entregar um momento emocional que a leitora não pediu. Uma nota concisa e factual não é fria, é respeito pelo estado real da leitora, que sob pressão real é impaciência, não necessidade de conforto.
FAQ
Uma release note de emergência deveria passar pelo mesmo processo de revisão que uma normal? Uma versão mais leve, não nenhuma: uma revisora rápida checando que a nota não exagera certeza vale os poucos minutos que exige, porque o risco de uma afirmação técnica não revisada estar errada é maior justamente por ela ter sido escrita rápido.
Está tudo bem publicar uma nota de emergência sem link para mais detalhes? Só brevemente. Uma nota sem link é aceitável como a primeira coisa publicada; adicione um link para uma página de status ou nota de acompanhamento assim que qualquer uma das duas existir, porque uma leitora que quer mais que aquela única frase que você deu precisa de um lugar para ir, mesmo que esse lugar diga “mais detalhes em breve”.
Uma nota de emergência deveria alguma vez ser pulada completamente, deixando a correção sair em silêncio? Só para problemas que nenhuma leitora poderia ter notado ou sido afetada por eles; se há alguma chance de uma leitora ter experimentado o problema, a nota é o que diz a ela que acabou, e o silêncio lê como se o problema ainda pudesse estar ativo.
Por quanto tempo uma nota de emergência deveria continuar fixada ou em destaque depois que o incidente é resolvido? Até a janela de ansiedade imediata fechar, geralmente um dia ou dois, e então ela pode se dobrar no changelog normal como qualquer outra entrada; uma nota que permanece fixada por semanas começa a ler como uma preocupação não resolvida em vez de uma resolvida.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.