Changelogs vs Notas de Versão: Uma comparação detalhada

O que é um changelog?

Um changelog é um documento detalhado que fornece uma visão geral de todas as alterações, atualizações, melhorias e correções feitas em um produto de software ao longo do tempo.

Geralmente, está em ordem cronológica inversa, mostrando as alterações mais recentes na parte superior da página e as versões anteriores do produto no final da página.

Pode ser assim:

Ou assim:

Cabe a você anunciar (ou não) seus próximos recursos ou os projetos em que sua equipe de desenvolvedores está trabalhando no momento. Dependendo dos seus produtos/serviços e da base de usuários, o tipo de sistema de rotulagem e categorização que você usa para as entradas do changelog também pode mudar.

Independentemente dessas diferenças estratégicas, um bom changelog deve ser sempre claro e organizado. Ele deve permitir que seu público-alvo navegue facilmente para encontrar as informações relevantes. Mas discutiremos o que faz um bom changelog nas próximas seções, portanto, não se preocupe com isso por enquanto.

O que é uma nota de versão?

Semelhante a um changelog, uma nota de versão é um documento que fornece informações sobre novos recursos, aprimoramentos de produtos e atualizações importantes.

No entanto, ao contrário das entradas do changelog, que incluem até mesmo as menores correções de bugs, as notas de versão incluem, em sua maioria, apenas as alterações significativas e os principais aprimoramentos de recursos que provavelmente afetarão a experiência do usuário.

As notas de versão também são mais amigáveis e fáceis de ler, pois não contêm jargões técnicos. Elas também são apoiadas por recursos visuais, como vídeos ou capturas de tela da interface do usuário.

As notas de versão permitem mais liberdade em termos de estrutura e design. Portanto, elas diferem mais umas das outras em comparação com os designs e estruturas relativamente semelhantes dos changelogs.

Entretanto, aqui estão alguns exemplos:

Como você pode ver, uma nota de versão não é necessariamente uma comunicação unidirecional em que você compartilha suas notícias e atualizações enquanto seus clientes apenas ouvem (ou leem). Você também pode transformá-la em uma experiência interativa, oferecendo uma chance para que os clientes forneçam feedback ou façam uma reação rápida.

Diferenças entre changelogs e notas de versão

Embora tanto as notas de versão quanto os changelogs sejam meios para as equipes de produtos anunciarem alterações ou melhorias, eles diferem significativamente em sua estrutura, no uso da linguagem e em vários outros aspectos.

Vamos ver como 🔎

Público-alvo

Os changelogs e as notas de versão se dirigem a públicos diferentes. Enquanto os changelogs são lidos principalmente por desenvolvedores e usuários técnicos, as notas de versão atraem um público amplo, como usuários não técnicos e partes interessadas.

Na verdade, todas as outras diferenças entre as notas de versão e os changelogs se originam dessa diferença principal.

Nível de detalhe

Os changelogs são basicamente listas abrangentes de todas as alterações feitas desde a primeira introdução do produto até hoje, o que significa que eles incluem até mesmo as menores correções e melhorias.

Já as notas de versão concentram-se nos principais recursos, melhorias e introduções que são relevantes para a experiência geral do usuário. Como se trata de um público não técnico, não é necessário incluir pequenas correções de bugs se elas não forem radicalmente importantes ou mesmo perceptíveis para o usuário comum.

Tom e estilo

Embora as entradas do changelog tendam a ser mais detalhadas em termos das alterações que incluem, elas não são necessariamente mais explicativas ou fáceis de entender.

Os changelogs geralmente não fornecem instruções detalhadas ou casos de uso para novos recursos. Eles descrevem a natureza da alteração, mas não são muito detalhados e usam uma linguagem mais técnica, pois são destinados aos desenvolvedores.

Por outro lado, as notas de versão tendem a ser mais explicativas e instrutivas. Elas usam uma linguagem mais clara, concisa e fácil de usar, muitas vezes incluindo exemplos de casos de uso, benefícios e explicações adicionais.

O objetivo de um changelog é informar um desenvolvedor ou usuário técnico sobre uma alteração, sem necessariamente motivá-lo a agir.

Em contrapartida, uma nota de versão não apenas informa os usuários sobre uma alteração, mas também os incentiva a agir, como experimentar um novo recurso. Portanto, as notas de versão geralmente incluem gatilhos motivacionais, como propostas de valor e instruções.

Formato e estrutura

Os changelogs geralmente são formatados em ordem cronológica inversa. As notas de versão, por outro lado, são estruturadas para destacar primeiro as atualizações mais importantes.

Eles geralmente são categorizados por novos recursos, melhorias e correções de bugs para facilitar a leitura. Os changelogs também incluem um grande número de detalhes técnicos, como números de versão, números de problemas, datas de lançamento, trechos de código etc.

Embora todos esses itens também possam estar disponíveis em uma nota de versão, na maioria das vezes, eles não são incluídos para não sobrecarregar os usuários com muitos detalhes técnicos e são mantidos apenas nos changelogs.

Uso de recursos visuais

Outra diferença importante entre os changelogs e as notas de versão é o uso de recursos visuais, como capturas de tela da UI ou vídeos explicativos e tours guiados pelo produto.

Embora algumas empresas, como o Mixpanel, incorporem recursos visuais - até mesmo vídeos - em seus changelogs, não é muito comum adicionar GIFs, capturas de tela ou vídeos de tour guiado de produtos às entradas do changelog (mas vemos muitos trechos de código, se quisermos contá-los como recursos visuais também).

No entanto, como as notas de versão são destinadas a usuários não técnicos, elas tendem a incorporar muitos recursos visuais para ajudar os alunos visuais a entender como o novo recurso se parece e funciona.

Melhores casos de uso de changelogs e notas de versão (+ exemplos)

Todas essas diferenças entre changelogs e notas de versão não significam que um é perfeito e o outro é terrível. Em vez disso, elas tornam cada um adequado para diferentes casos de uso, que podem ser listados da seguinte forma 👇🏻

Os changelogs são bons para:

• Rastreamento do histórico do projeto e das alterações de código.
• Fornecimento de informações detalhadas para desenvolvedores e equipes técnicas.
• Criar um ponto de referência para equipes internas, como equipes de suporte.
• Manter a transparência e manter as partes interessadas informadas.  

As notas de versão são boas para:

• Anúncio de novos recursos e atualizações para um público geral.
• Destacar casos de uso e propostas de valor para os usuários finais.
• Incentivar os usuários a experimentar um novo recurso ou integração.
• Criar um ponto de referência para as equipes internas, como as equipes de vendas, de sucesso do cliente e de marketing.
• Comunicação com os usuários finais e coleta de feedback após os lançamentos.

Vamos ver alguns exemplos reais desses casos de uso 👀

1- O CoScreen explica por que os usuários devem experimentar seu novo recurso

O CoScreen é uma ferramenta colaborativa de compartilhamento de tela criada especificamente para equipes de desenvolvimento de produtos e equipes de engenharia.

E aqui está uma nota de versão do CoScreen:

Agora, como o CoScreen é uma ferramenta SaaS para desenvolvedores, até mesmo suas notas de versão têm jargão técnico. Mas ainda é uma nota de versão e não um changelog.

Nós sabemos como?

Porque não se trata apenas de anunciar: "Ei, lançamos o CoTerm Beta!" e passar para outras mudanças no produto. Em vez disso, ele fornece motivações para que os usuários sejam incentivados a experimentar o recurso.

⚠️ Portanto, mesmo que sua base geral de clientes seja composta por desenvolvedores e programadores que possam entender as entradas do changelog, você ainda precisará de notas de versão juntamente com um changelog para comunicar suas propostas de valor aos usuários.

2- O Notion lista (pequenas ou grandes) todas as alterações e atualizações

O Notion é uma das ferramentas mais populares de anotações e espaço de trabalho.

E este é o aspecto de seu changelog:

Há changelogs projetados especificamente para anúncios de produtos, completos com rótulos, categorias e entradas separadas para cada atualização. E há changelogs projetados para manter um histórico abrangente do produto ao longo do tempo.

Este é um exemplo do segundo tipo de changelog.

O Notion oferece um relatório muito detalhado e minucioso do que sua equipe de desenvolvedores realizou, documentando todas as alterações, sejam elas grandes ou pequenas.

Eles acrescentaram esclarecimentos à documentação do produto?

Ele vai para o changelog.

3- O Slack garante transparência ao destacar atualizações importantes

Você conhece o Slack. E eu sei que você conhece o Slack.

Então, vamos pular a introdução e pular para o changelog do Slack 🦘

O changelog do Slack funciona de forma semelhante ao do Notion, listando as atualizações mais recentes primeiro e as mais antigas mais abaixo na página.

Mas o que o Slack faz de diferente é colocar atualizações importantes, como mudanças de política ou depreciações, bem no topo, em uma seção chamada "Atualizações importantes". Assim, mesmo que algo tenha sido anunciado em março ou abril, se ainda for relevante, você o verá imediatamente ao abrir o changelog.

Assim:

4- O Miro primeiro aborda os pontos problemáticos dos clientes e depois oferece soluções

O Miro é uma ferramenta de colaboração digital e quadro branco que permite que as pessoas colaborem em projetos, apresentações, mapas mentais e roteiros.

Aqui está um trecho de uma de suas notas de versão mensais:

O que o Miro faz aqui é falar diretamente com as necessidades insatisfeitas de um determinado segmento de usuários: grandes empresas. Depois de abordar seus pontos problemáticos, ele oferece uma solução para os problemas e apresenta sua proposta de valor.

O mesmo vale para a segunda nota de recurso. O Miro mostra que entende seus clientes e o que eles precisam, e sua equipe de desenvolvedores está trabalhando para garantir a satisfação e a felicidade deles.

5- A UserGuiding coleta feedback diretamente em sua página de atualizações do produto

A UserGuiding é uma ferramenta completa de adoção de produtos que permite que as equipes criem fluxos interativos in-app, centrais de recursos, pesquisas com clientes e páginas de atualizações do produto.

E aqui está a aparência de sua página de atualizações do produto:

• Etiquetas: ✅
• Microcópia amigável ✅
• Comunicação bidirecional ✅

A UserGuiding não usa apenas a página de atualizações de produtos para publicar notas de versão; ela também a usa para coletar feedback (por escrito ou reações) de seus usuários. Isso cria uma oportunidade de testar as águas e se engajar diretamente com seus usuários.

Pode ser difícil identificar qual avaliação de usuário corresponde a uma atualização ou recurso específico, especialmente quando as empresas lançam várias alterações em um curto período, como atualizações mensais.

No entanto, com esse sistema, embora as empresas possam atribuir avaliações de usuários a atualizações específicas, os usuários podem enviar solicitações de recursos ou deixar comentários - até mesmo de forma anônima!

👉🏻 Experimente você mesmo 👈🏻

Práticas recomendadas para changelogs

Agora que vimos alguns exemplos e nos familiarizamos com os changelogs, vamos discutir as práticas que transformam os changelogs medíocres em excelentes.

Crie um sistema (e mantenha-o)

Um changelog não é uma lixeira de atualizações do produto.

Quer você publique as alterações e melhorias do seu produto como entradas separadas ou como um documento interminável, você precisa de um sistema.

Aqui estão algumas sugestões:

• Usar rótulos e tags para categorizar suas entradas (novos recursos, correções de bugs, melhorias na UI, alterações na API, etc.).
• Implementar recursos de pesquisa e filtro.
• Criar um modelo pronto para preencher para números de versão, números de tíquetes, números de problemas, autores, planos afetados, data de lançamento, etc.
• Destacar atualizações importantes com formatação, como negrito ou programação por cores, ou no início do documento de registro de entrada/alteração.
• Arquivar versões antigas.

Garantir a clareza

Os changelogs servem como documentação técnica voltada principalmente para desenvolvedores e usuários técnicos. Embora não seja necessário explicar detalhadamente cada termo técnico, é essencial usar uma linguagem técnica precisa e fornecer detalhes específicos.

Por exemplo, ao introduzir uma atualização importante em um esquema de banco de dados, inclua instruções claras sobre as alterações no esquema, etapas de migração e qualquer impacto potencial nas estruturas de dados existentes; ou ao atualizar uma API, é útil incluir instruções detalhadas sobre sua implementação.

Você pode explicar esses detalhes em caixas de texto suspensas para manter o changelog organizado e fácil de ler.

Se não conseguir encaixar todas as instruções e explicações em uma caixa de texto suspensa (ou se puder, mas for ineficiente), você poderá criar guias de instruções separados em sua base de conhecimento ou artigos de ajuda e vinculá-los ao changelog.

Você também pode incorporar recursos visuais e trechos de código.

Use integrações de controle de versão

Se você não quiser trabalhar em um modelo detalhado de changelog - ou usar uma ferramenta de changelog de terceiros - mas ainda quiser comunicar alterações técnicas e aprimoramentos de recursos a outros desenvolvedores, poderá automatizar seu changelog vinculando-o aos commits do Git.

Quando você faz alterações em sua base de código, como corrigir bugs, adicionar novos recursos ou melhorar os existentes, as mensagens de confirmação preenchem automaticamente o changelog e documentam cada atualização em tempo real.

Agora, essa integração não fornece explicações ou descrições adicionais, a não ser as próprias alterações.

Portanto, você ainda precisa escrevê-las se quiser que seu changelog seja útil e proveitoso. No entanto, ele ainda é útil, pois você não precisa voltar e listar manualmente todas as alterações que sua equipe fez naquele dia/semana/mês/trimestre.

Portanto, esse é um bom ponto de partida, digamos.

Práticas recomendadas para notas de versão

Veja o que você pode fazer para melhorar suas notas de versão 👇🏻

Personalizar o conteúdo

As notas de versão incluem pouco ou nenhum jargão técnico (a menos que seus clientes sejam apenas desenvolvedores, como é o caso da CoScreen). Entretanto, os usuários não técnicos não são todos iguais. O pessoal de produto, o pessoal de vendas e o pessoal de marketing falam uma linguagem diferente. Portanto, dependendo da sua própria base de usuários, adapte o conteúdo e a linguagem.

Destaque a proposta de valor

Lembre-se de que você não está apenas comunicando seu novo recurso; você está atendendo a uma necessidade do usuário e oferecendo uma solução. Portanto, é importante que você fale a mesma língua que seus usuários ao escrever as notas de versão, não apenas no sentido técnico, mas também em termos de necessidades e expectativas.

Assim como você deve evitar uma linguagem excessivamente técnica, também deve evitar um tom de vendas. Opte por uma linguagem simples. Não se trata de um documento exclusivamente técnico, nem de um discurso de vendas, portanto, encontre um meio termo.

Em uma nota de versão, você pode incluir:

• Uma breve descrição dos novos recursos;
• Casos de uso/ vantagens;
• Necessidades não atendidas dos clientes (que serão atendidas com esses novos recursos).

Mantenha-o digerível

Dependendo das estratégias do seu produto, você pode publicar notas de versão mensalmente, trimestralmente ou sempre que lançar uma nova atualização. O tamanho das notas de versão pode variar de acordo com o momento e a complexidade dos novos recursos. No entanto, você deve mantê-las o mais breves e fáceis de entender - e ler - possível.

Você também deve elaborar estratégias de formatação para evitar que seus usuários fiquem angustiados, especialmente se planeja publicar notas de versão longas.

Você pode:

• Usar títulos, resumos, marcadores e emojis;
• Incorporar capturas de tela e vídeos de tour guiado pelo produto para recursos complexos;
• Usar links para artigos de ajuda ou guias de instruções para obter detalhes técnicos.

Principais conclusões

• Os changelogs oferecem um registro histórico completo para públicos técnicos, enquanto as notas de versão fornecem um resumo acessível das atualizações para uma base de usuários mais ampla.
• Ambos os documentos são essenciais para manter a transparência, garantir uma comunicação eficaz e aprimorar a experiência geral do usuário.
• Ambos são pontos de referência valiosos para as equipes internas. Os changelogs, com seu foco em correções de bugs e implementações técnicas, servem como pontos de referência para equipes como suporte ao cliente e sucesso. Já as notas de versão, com suas explicações detalhadas e propostas de valor, são pontos de referência para equipes como vendas e marketing.

Os changelogs usam linguagem técnica e geralmente são estruturados como listas concisas com pouca ou nenhuma explicação adicional. As notas de versão usam linguagem narrativa e destacam alterações significativas, seus benefícios para o usuário e casos de uso com explicações e exemplos claros e detalhados.