Pular para o conteúdo
Build log · ● Aeternum

Aeternum: ajuda em cada tela, sem sair do painel

Por que cada uma das 29 telas do Aeternum ganhou um botão de ajuda com passo a passo, em vez de eu depender do runbook guardado fora do sistema.

Projeto: AeternumWillian D. Santos3 min de leitura
commit
442122d (aeternum)
Author:
Willian D. Santos
Date:

Aeternum: ajuda em cada tela, sem sair do painel

registro 3 de 3 no ramo aeternum

Contexto

O Aeternum cresceu e hoje tem 29 telas, entre CRM, Audiência, Rastreamento e Ajustes. Eu uso o sistema em intervalos, dividido entre projetos, e ao voltar não lembro o que cada tela faz nem o que precisa estar configurado para ela funcionar. Essa informação existia só no runbook e nas specs, que ficam no repositório, fora do sistema. Na prática, eu tinha de sair do painel para entender o painel.

O que mudou

  • Toda tela do painel tem um botão (i) no canto superior direito, que abre uma janela com o tutorial daquela tela.
  • O botão fica no layout do admin, sempre no mesmo lugar, e reconhece a rota e a aba aberta para mostrar o texto certo.
  • Os textos ficam num registro único, como dados tipados, sem markdown em execução.
  • Cada ajuda segue as mesmas seções: para que serve, como usar, o que precisa para funcionar, o que fazer se algo der errado e a fase do runbook que cobre a tela.
  • Escrevi a ajuda das telas do CRM, da Audiência, do Rastreamento e dos Ajustes.
  • Incluí no AGENTS.md uma regra: tela nova entra com a ajuda dela, e mudança de comportamento atualiza a ajuda.

A decisão

Escolhi colocar a ajuda dentro do próprio painel, no mesmo lugar em todas as telas, em vez de manter só o runbook no repositório. O runbook continua existindo e cada ajuda cita a fase correspondente pelo nome, para quem quiser mais detalhe.

Uma regra que mantive: os textos são escritos a partir do código da tela e do runbook atuais, nunca de memória. Todo nome de botão, campo ou aba citado precisa existir na tela, e a revisão confere isso. Foi por essa conferência que fiz correções depois: a ajuda do CRM, dos Ajustes e da Audiência estava imprecisa em alguns pontos, e a revisão final ainda pegou mais. Também limitei cada ajuda a cerca de 250 palavras, sem segredo, valor de variável ou dado pessoal.

O que descartei foi deixar a documentação só como arquivo de repositório, porque era justamente isso que não funcionava no meu uso.

Por que importa

Eu consigo voltar ao sistema depois de dias e entender uma tela em poucos segundos, sem abrir o runbook. A seção do que precisa estar configurado evita aquela perda de tempo de descobrir que uma tela não funciona porque falta uma integração ligada. E a regra no AGENTS.md impede que a ajuda envelheça: ela passa a fazer parte de entregar uma tela.

Pendências e próximo passo

  • Usar a ajuda no dia a dia e anotar onde ainda falta um sintoma comum ou um passo.
  • Manter os textos em dia a cada mudança de comportamento das telas.
  • Seguir conferindo se os nomes citados continuam iguais aos da tela.

Registro escrito depois da decisão, a partir dos commits e da documentação do projeto.

Ver o projeto Aeternum →