Como criar uma página de changelog: entradas, etiquetas, RSS e “Novidades”

Uma página de changelog é uma lista datada do que mudou no seu produto, da mais recente para a mais antiga, escrita para as pessoas que o usam. Para a construir precisa de entradas com data, um título claro, uma explicação curta e uma etiqueta (Novo, Melhorado, Corrigido), uma página que as liste, um URL separado por entrada e, idealmente, um feed RSS e uma forma de dizer aos utilizadores que há novidades. É uma das coisas mais simples que pode construir, e a principal decisão é onde vivem as entradas: como ficheiros no seu site, ou numa base de dados com uma página de administração.

Porque vale a pena ter um changelog

Um changelog mostra a clientes e potenciais clientes que o produto está a ser mantido. Dá à equipa de apoio e de vendas uma ligação para enviar quando alguém pergunta “isto já faz X?”. É também um sítio para fechar o ciclo do feedback: quando uma funcionalidade pedida é lançada, a entrada do changelog é o que aponta às pessoas. Se gere um portal de feedback de clientes, ligue os pedidos lançados diretamente às suas entradas.

Um changelog não é o histórico interno de commits. “Refatorado o serviço de faturação” não diz nada a um utilizador. “As faturas passam a mostrar o número de IVA da sua empresa” diz.

O que a página precisa

Conteúdo de cada entrada

Páginas

• Índice do changelog: da mais recente para a mais antiga, com filtros por etiqueta e paginação simples ou “carregar mais”.
• Página da entrada: uma entrada por URL, para poder ser ligada e partilhada.
• Feed RSS ou Atom: permite que as pessoas e as ferramentas acompanhem as atualizações sem email.
• Página de administração (apenas na versão com base de dados): escrever, pré-visualizar, agendar e publicar entradas.

Extras na app

• Distintivo de “Novidades”: um ponto num item do menu quando há entradas que o utilizador ainda não viu. Guarde a data da última entrada que ele abriu, por utilizador ou no navegador.
• Resumo por email: um resumo enviado aos utilizadores que optam por o receber. Isto precisa de um fornecedor de envio; veja como enviar emails a partir da sua app.

A decisão principal: ficheiros ou base de dados

Entradas como ficheiros no site

Cada entrada é um ficheiro Markdown no projeto. Publicar uma entrada significa acrescentar um ficheiro e voltar a implementar. É a abordagem mais simples e robusta: sem base de dados, sem página de administração com início de sessão, nada para proteger, e as páginas podem ser pré-renderizadas para carregarem depressa e serem fáceis de ler pelos motores de busca.

Adequa-se a equipas em que quem escreve as entradas se sente confortável a pedir ao criador de IA ou a editar um ficheiro.

Entradas numa base de dados com página de administração

As entradas vivem numa tabela, e uma página de administração privada permite que qualquer pessoa da equipa escreva, pré-visualize, agende e publique. Adequa-se a equipas em que o marketing ou o apoio escrevem as atualizações, ou quando quer publicação agendada ou entradas por público (por exemplo, mostrar funcionalidades empresariais apenas a clientes empresariais).

O custo é mais trabalho de construção e manutenção: um início de sessão de administração, carregamento de imagens e garantir que as páginas públicas continuam legíveis pelos motores de busca, o que pode não acontecer numa página que apenas carrega as entradas no navegador.

Escrever entradas que as pessoas leem

• Comece pelo benefício. “Exportar relatórios para Excel” é melhor do que “Novo módulo de exportação”.
• Diga quem a recebe. Todos os planos, apenas Pro, a ser disponibilizado esta semana.
• Mostre-a. Uma captura de ecrã ou um pequeno vídeo.
• Agrupe as pequenas correções. Uma entrada semanal de “Correções e melhorias” com pontos mantém a página sem ser inundada.
• Seja honesto sobre remoções. Se algo vai desaparecer, diga quando e o que usar em alternativa.

Um primeiro pedido que funciona

Acrescente um changelog público ao nosso site em /changelog. Cada entrada é um ficheiro Markdown com título, data, etiqueta (Novo, Melhorado ou Corrigido), imagem de capa opcional e corpo. A página de índice lista as entradas da mais recente para a mais antiga com a data, a etiqueta e o primeiro parágrafo, tem botões de filtro por etiqueta e mostra 10 entradas por página. Cada entrada tem a sua própria página em /changelog/<slug> com um título e uma descrição de página adequados para os motores de busca. Acrescente um feed RSS em /changelog/rss.xml. Crie três entradas de exemplo. Siga o design do site existente, mantenha-o legível em telemóveis e pré-renderize as páginas para carregarem depressa.

Para a versão com base de dados, substitua a primeira frase por “Guarde as entradas numa base de dados com estado de rascunho/publicado e uma data de publicação, e acrescente uma página de administração protegida por palavra-passe para escrever, pré-visualizar e publicar.”

Passos de construção

1. Decida ficheiros ou base de dados com a tabela acima.
2. Construa as páginas de índice e de entrada com algumas entradas de exemplo.
3. Acrescente etiquetas e filtros.
4. Acrescente o feed RSS e ligue-o a partir da página.
5. Acrescente títulos de página, descrições e uma entrada no sitemap para cada entrada. O nosso guia sobre SEO para sites criados com IA cobre o básico.
6. Página de administração e início de sessão, se escolheu o caminho da base de dados.
7. Distintivo de “Novidades” na sua app.
8. Escreva entradas reais dos últimos meses para que a página não seja lançada vazia.

Erros comuns

• Copiar mensagens de commit. Escreva para os utilizadores, não para os programadores.
• Uma página gigante sem URLs por entrada. Ninguém consegue ligar a uma alteração específica, e os motores de busca veem uma página em vez de muitas.
• As atualizações param ao fim de um mês. Um changelog sem atualizações há um ano sugere um produto abandonado. Defina um ritmo que consiga manter.
• Carregar as entradas apenas no navegador. Os motores de busca e as pré-visualizações de ligações podem ver uma página vazia. Pré-renderize ou renderize no servidor.
• Misturar incidentes. As interrupções pertencem a uma página de estado, e não ao changelog.

Quando uma ferramenta de changelog alojada é a melhor escolha

Existem ferramentas alojadas de changelog e de atualizações de produto, e algumas vêm incluídas em quadros de feedback ou widgets na app. Valem a pena se quer um pop-up na app, segmentação de público e análises sem as construir, ou se a sua equipa já paga uma ferramenta que inclui uma. O software de blogue ou de centro de ajuda também pode ter um formato adequado.

Construir o seu próprio faz sentido quando quer o changelog no seu próprio domínio, com o seu próprio design, e totalmente indexável — o que, para uma lista simples de publicações datadas, não dá muito trabalho.

Criar com a Mythex

Na Mythex pode pedir ao agente que acrescente um changelog a um projeto existente ou que o construa como um pequeno site próprio, e vê-lo na pré-visualização em tempo real à medida que é construído. A versão baseada em ficheiros não precisa de base de dados. Se escolher a versão com administração, o agente acrescenta uma base de dados Postgres dedicada quando as entradas precisarem de ser guardadas (ou escreva /database), e as capturas de ecrã vão para o armazenamento de ficheiros do projeto. O início de sessão de administração é algo que acrescenta com a sua própria abordagem de autenticação (receita de início de sessão).

As novas apps da Mythex são muitas vezes aplicações de página única renderizadas no cliente, que a receita de SEO indica como mais fracas para a pesquisa; por isso, peça páginas de changelog estáticas ou pré-renderizadas se quer que as entradas sejam encontradas na pesquisa. A mesma receita cobre títulos, descrições e sitemaps. Como ponto de partida com um changelog incluído, veja o modelo hub de conhecimento do produto.

Perguntas