Como criar uma página de changelog sem escrever código

Como criar uma página de changelog sem escrever código

Uma página de changelog nasce de um texto simples: o que mudou no seu produto, quando mudou e para quem aquilo importa. O Zugo transforma essa descrição em uma página publicada, testada em uma sandbox antes da entrega, no endereço .zugo.run ou no seu domínio.

A parte difícil não é publicar a primeira versão. É a terceira semana, quando o entusiasmo passou e a página começa a envelhecer enquanto o produto continua mudando.

Para que serve mesmo uma página de changelog?

Para três públicos distintos, e confundir os três é o motivo mais comum de changelog abandonado.

O primeiro é o cliente que já usa o produto e quer saber o que mudou na tela dele. Esse público quer texto curto, benefício claro e nenhuma menção a nome interno de módulo. Ele não sabe o que é o "serviço de sincronização" e não deveria precisar saber.

O segundo é o cliente em potencial, que usa o changelog como prova de vida. Um produto com entradas recentes parece cuidado; um produto com a última nota de oito meses atrás levanta a pergunta se a empresa ainda existe. Esse público lê pouco e olha datas.

O terceiro é a sua própria equipe, que consulta o histórico para lembrar quando algo entrou. É o único público que aguenta detalhe técnico, e é o que menos deve ditar o tom da página pública.

Se você tentar servir os três com o mesmo texto, o resultado agrada o terceiro e afasta os outros dois. Escreva para o cliente e deixe o detalhe técnico no repositório.

O que entra em cada entrada?

Cinco elementos, e o quinto é o que quase todo mundo esquece.

A data, sempre visível e no formato brasileiro. O título em linguagem de usuário, começando por verbo: "Exportação de relatórios em planilha" funciona melhor que "Feature: export module v2". A categoria, para a pessoa saber se aquilo é novidade, melhoria ou correção.

O quarto é o texto de duas ou três frases dizendo o que muda na prática e para quem. "Quem usa o plano de equipe agora consegue exportar o relatório mensal direto em planilha, sem passar pelo suporte" comunica mais que qualquer lista de campos alterados.

O quinto elemento é o que fazer com aquilo. Um link para a documentação, para a tela onde a novidade vive ou para um vídeo curto. Sem essa linha, a entrada informa e não gera uso, e uma novidade que ninguém experimenta é indistinguível de uma novidade que não existe.

Agrupar por versão, por data ou por tipo?

Depende de quem lê e de como o seu produto entrega. Escolha um dos três e mantenha, porque misturar é o que faz a página ficar difícil de varrer.

O misto por mês é o mais fácil de sustentar em equipe pequena. Ele perdoa a semana sem entrega, porque o bloco do mês continua parecendo cheio, e evita a sensação de abandono que uma única entrada solta no topo produz.

Seja qual for a escolha, deixe as etiquetas de tipo com cores distintas e nomes curtos. Quem chega ao changelog quase nunca lê tudo: ele varre procurando as novidades e ignora as correções, e a etiqueta é o que torna essa varredura possível.

O que escrever no prompt?

O Zugo constrói a partir de uma descrição, então ela precisa conter a estrutura que você escolheu acima.

Crie uma página de changelog para um produto chamado [nome].
Estrutura:
1. Topo: nome do produto, uma linha explicando que aqui ficam
   as novidades, link de volta para o produto.
2. Filtro por tipo: Novidade, Melhoria, Correção.
3. Lista de entradas agrupadas por mês, mais recente no topo.
   Cada entrada tem data, etiqueta de tipo, título em uma linha,
   texto de duas ou três frases e um link "Ver como funciona".
4. Rodapé: link para a documentação e para o canal de sugestões.
Sem números de versão internos no título das entradas.
Data no formato dia/mês/ano. Idioma português do Brasil.
Comece com [N] entradas de exemplo que eu vou substituir.

A última linha é a que mais economiza trabalho. Pedir entradas de exemplo entrega o formato pronto, e substituir texto dentro de uma estrutura existente é bem mais rápido que descrever a estrutura de novo em cada edição.

Changelog dentro do produto ou em endereço separado?

Depende de quem você quer que leia. As duas opções são legítimas e resolvem problemas diferentes.

Dentro do produto, o changelog é lido por quem já usa. Ele aparece quando a pessoa está trabalhando, e por isso gera uso da novidade. A desvantagem é que ele fica atrás do login, então não ajuda quem está avaliando o produto de fora.

Em endereço público, ele vira material de venda e material de busca. Um changelog aberto é indexável, é linkável em resposta a cliente e serve de prova de ritmo. Com o Zugo, esse é o caminho natural: uma página publicada em .zugo.run ou no seu domínio, separada do aplicativo.

Muitos times fazem os dois: página pública como fonte e um aviso curto dentro do produto apontando para ela. Isso evita escrever a mesma coisa duas vezes com palavras diferentes, que é como changelog e aviso interno acabam se contradizendo.

Como manter atualizado sem virar tarefa esquecida?

Com um combinado de escrita, não com força de vontade. Todo changelog morto morreu do mesmo jeito: ninguém era responsável por ele.

O combinado que funciona tem três partes. Uma pessoa responsável por publicar. Um dia fixo, de preferência o mesmo toda semana. E um rascunho acumulado durante a semana, para que o dia de publicar seja um dia de revisar e não de lembrar.

A segunda regra é escrever a entrada quando a mudança entra, não quando a página é atualizada. A memória de por que aquilo importava para o cliente dura dois dias. Depois disso, o texto sai técnico, porque só o que ficou na cabeça foi o que você mexeu no código.

A terceira é aceitar que semana sem entrega não é problema. Melhor um mês com três entradas boas que um mês com doze entradas de "ajustes diversos". Entrada sem conteúdo treina o leitor a ignorar a página.

Quanto custa em créditos manter um changelog vivo?

Aqui está a conta honesta, e ela precisa ser feita antes de você escolher esse caminho.

O plano gratuito dá 5 créditos, abaixo de uma construção completa. O Pro custa $25 por mês com 200 créditos, algo como 16 plataformas multipágina, 33 construções ou 66 edições. O Business custa $99 por mês com 800 créditos.

A dica prática: acumule as entradas da semana e publique todas em uma edição só. Um time que edita a cada mudança gasta várias vezes mais que um time que edita uma vez por semana, e a página fica exatamente igual para quem lê.

Onde o changelog encosta em documentação e status?

São três páginas vizinhas com funções distintas, e trocá-las gera confusão em quem lê.

A documentação diz como usar o produto hoje. Ela está sempre no presente e é reescrita quando algo muda. O changelog diz o que mudou e quando, sempre no passado, e nunca é reescrito.

A página de status diz se o produto está funcionando agora. Ela vive em outra frequência: minutos, não semanas. Colocar incidente no changelog polui o histórico de produto com ruído de operação. O guia de página de status trata desse formato, e site de documentação cobre a parte de manual.

O quarto vizinho é o canal de sugestões, onde o cliente pede o que quer. Fechar o ciclo entre pedido e entrega é o que faz o changelog ser lido: quando a entrada diz que aquilo saiu de um pedido da comunidade, a página deixa de ser aviso e vira conversa. O formato está em mural de feedback.

O que essa página não resolve?

Três limites honestos.

Ela não se atualiza sozinha a partir do seu repositório. Cada publicação é uma edição feita por uma pessoa. Se o seu time entrega várias vezes ao dia e quer o changelog gerado do histórico de commits, isso é integração, e o caminho é exportar o código pelo GitHub e automatizar de lá.

Ela não avisa ninguém. Página publicada não é notificação: quem não visitar não vai saber. Se o aviso importa, o e-mail continua sendo o canal, e o Resend cuida desse envio a partir do projeto.

E ela não conserta comunicação ruim. Changelog é o resumo do que o produto fez, não substituto de conversa com cliente grande. Uma entrada de três linhas sobre uma mudança que quebrou o fluxo de alguém não evita o telefonema, e nem deveria.

Por onde começar?

Comece pelas últimas dez mudanças reais do seu produto, escritas em linguagem de cliente. Se você não conseguir explicar cinco delas sem usar nome interno, o problema não é a página: é o texto, e ele se resolve antes da construção.

Com essas entradas prontas, uma construção entrega a página e uma edição semanal a mantém viva. Escolha o agrupamento, defina o responsável e o dia fixo, e trate a primeira publicação como o começo de uma rotina e não como um projeto que termina.

Dá para montar em zugo.dev pelo plano gratuito, publicar no endereço .zugo.run para o time revisar e conectar o domínio quando o formato estiver do jeito que vocês querem manter.