Uma página de changelog que as pessoas realmente acompanham

Uma página de changelog vale a pena construir quando alguém voltaria a ela. Essa é uma régua mais alta do que simplesmente ter uma, e é a régua onde a maioria falha: uma página que existe, tem link no rodapé, é atualizada aos trancos e barrancos e não é visitada por ninguém exceto durante um incidente. As decisões que separam as duas são tomadas antes de qualquer coisa ser escrita, e são principalmente sobre onde a página vive e o que mais é gerado a partir do mesmo conteúdo.

O que é uma página de changelog?

É a lista pública e datada do que mudou em um produto, em uma URL que pertence a você. É uma de cinco superfícies onde as mesmas entradas podem aparecer, e a pergunta útil não é qual escolher, mas qual é canônica e quais são geradas a partir dela.

Escolha uma fonte canônica, publique uma vez, e gere o resto. Times que mantêm a página e o widget separadamente à mão acabam com dois textos que não batem, e a discrepância é descoberta por um cliente.

Onde uma página de changelog deve viver?

No seu próprio domínio, em um caminho estável, com cada entrada endereçável individualmente. Os três locais comuns são um caminho no site principal, um subdomínio, e uma seção da documentação. Um caminho no site principal é a escolha padrão contra a qual se deve argumentar, não a favor dela: herda a autoridade do site, não precisa de certificado ou DNS extra, e mantém a página na mesma navegação que tudo o mais.

Um subdomínio é a resposta certa quando a página é servida por um sistema diferente do site de marketing e você faria proxy de outra forma. O custo é que ele acumula autoridade separadamente. Colocar o changelog na documentação é certo quando o público são desenvolvedores, pelo motivo coberto em changelog de API: o leitor geralmente já está lá.

Mais importante do que a escolha é que as entradas possam ser linkadas individualmente. As pessoas linkam entradas em análises de incidentes e tickets internos, e uma entrada que só pode ser linkada como “o changelog, role para baixo” acaba colada como print de tela em vez disso.

O que uma página de changelog precisa?

Cinco coisas, e nas duas primeiras a maioria das páginas falha. Uma entrada datada por mudança, a mais recente primeiro. Uma categoria ou rótulo por entrada para poder escanear pelo tipo que interessa. Um link permanente por entrada. Uma rota de assinatura. Uma busca ou filtro depois de cerca de cinquenta entradas.

O resto é opcional. Prints de tela ajudam e custam manutenção. Nomes de autores constroem confiança em alguns produtos e são ruído em outros. Números de versão importam para chamadores de uma API e para quase mais ninguém. O Keep a Changelog é uma escolha padrão razoável para rótulos se você não tem motivo para inventar os próprios, e sua regra central é a que vale a pena manter mesmo que você descarte o resto: o log é escrito para pessoas.

Agrupe por data, não por versão, quando seu produto lança continuamente. Um leitor escaneando “isso foi antes ou depois do nosso incidente do dia nove” está procurando uma data, e uma página organizada por número de versão o obriga a fazer contas.

Página ou widget no app?

Os dois, de uma única fonte. A página é onde vivem a busca, os links e o registro longo. O widget é como você alcança a maioria dos usuários que nunca vão visitar a página, e funciona porque aparece no produto que eles já usam.

O fracasso do widget é a interrupção. Um badge que exige atenção para cada entrada é descartado permanentemente em uma semana, o que custa a você o canal para a entrada que realmente importava. Conte não lidas desde a última vez que o leitor olhou, plante o contador silenciosamente na primeira visita para que ninguém seja recebido com um badge de um ano de histórico, e deixe o leitor abri-lo em vez de abrir para ele.

Como tornar uma página de changelog legível por máquina?

Publique as mesmas entradas como feed. Um feed JSON é a opção de menor atrito para qualquer coisa que o consuma em código, e um feed RSS é o que um desenvolvedor assinando em um leitor espera. Os dois custam pouco assim que as entradas são dados estruturados em vez de HTML escrito à mão, o que é o argumento real para manter a cópia canônica estruturada.

Marque a página também. Entradas são obras com data e título, e o schema.org fornece o vocabulário. Vale a pena pelo mesmo motivo dos links permanentes: torna a página utilizável por coisas que não são um navegador, incluindo o próprio processo de release de um cliente. Nada disso funciona se as entradas subjacentes nunca foram dados estruturados desde o início; formatos de arquivo de changelog cobre quanto custa cada um entre Markdown, JSON e YAML como a fonte de verdade da qual esse feed e essa marcação são de fato gerados.

Uma página de changelog ajuda o SEO?

Indiretamente e devagar. Entradas individuais raramente rankeiam, porque não miram em nenhuma busca que alguém digita. A página ganha seu lugar através de links: entradas são citadas em respostas de suporte, fóruns e análises de incidentes, e esses links se acumulam em uma URL que pertence a você. Uma página atualizada semanalmente por dois anos também é um sinal de frescor confiável para o produto ao qual pertence.

O que não funciona é tratar entradas como marketing de conteúdo. Uma entrada inflada para três parágrafos por causa do tamanho fica pior no seu trabalho real, que é dizer ao leitor em uma frase se algo que ele usa mudou. Se você quer que o changelog apoie a busca, coloque o esforço nos links permanentes, no feed e nos links internos para ele, e mantenha as entradas curtas. Nossa própria página de exemplos de changelog reúne páginas que acertam esse equilíbrio.

Como as pessoas se inscrevem?

Dê a elas as rotas que já usam: um feed RSS ou JSON para desenvolvedores, e-mail para quem só quer ouvir as coisas importantes, e o widget no app para todos que nunca vão fazer nenhum dos dois. Pergunte o que elas querem ouvir em vez de assumir, porque um leitor que quer mudanças que quebram algo e recebe correções de texto se desinscreve dos dois.

A rota que vale a pena adicionar por último é a que fecha o loop. Quando uma entrada resolve algo que uma pessoa específica pediu, diga a ela diretamente, em vez de esperar que leia a página. No changeloop, a entrada é publicada de uma vez na página, no feed e no widget, e uma pessoa cujo feedback pelo widget virou a issue do GitHub que o pull request fechou é avisada nessa issue, com um link para a entrada, e vê a entrada no widget. O mecanismo é o mesmo de qualquer assinatura; a diferença é que quem recebe já perguntou. Esse é o argumento desenvolvido em fechar o loop de feedback pelo lado do changelog.

FAQ

A página de changelog deveria estar em um subdomínio ou em um caminho? Por padrão, um caminho no site principal, porque herda a autoridade do site e não precisa de infraestrutura extra. Um subdomínio se justifica quando um sistema diferente serve a página.

Quantas entradas a página deveria mostrar de uma vez? O suficiente para preencher uma tela e não mais, com paginação depois disso. Carregar dois anos de histórico em um único documento é lento e dificulta encontrar a entrada mais recente.

Entradas antigas deveriam algum dia ser apagadas? Não. Elas são citadas de fora do seu site, e os links quebram. Corrija uma entrada no lugar com uma nota, e mantenha a URL viva.

Toda mudança precisa aparecer na página? Só as que um usuário poderia notar. Uma página que registra refatorações internas treina os leitores a passar os olhos rapidamente, e uma página assim falha no dia em que carrega algo urgente.

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: Exemplos de changelog, Documentação para desenvolvedores