Como reorganizamos a documentação de um app antes que ela ficasse impossível de manter

O problema não era falta de documentação

O Daily Sudoku tinha documentação de sobra. Até demais.

Tínhamos plano de produto, guia do Google Play, copy de loja, pesquisa ASO, changelog, checklist do Play Console, notas de setup de IAP, benchmarks de performance e release notes. Cada arquivo fazia sentido quando nasceu. O problema apareceu depois, quando o app passou por teste interno, lançamento público, polish pós-lançamento e várias rodadas de preparação de release.

Nesse ponto, os documentos pararam de responder uma pergunta por vez.

O plano já não era só plano. Tinha hashes antigos de AAB, logs de validação, descrição de sistemas, estado do Play Console, ideias futuras e checklist concluído. O arquivo de listing ainda tinha release notes inline antigas. O changelog virou um scroll longo onde um dia de trabalho ficava enterrado entre meses de histórico sem relação. Um checklist que dizia não ser status log ainda guardava um snapshot datado do Play Console.

Nada disso parecia grave. Por isso é perigoso. Documentação apodrecendo raramente parece build quebrado. Parece hesitação: “onde coloco isso?” Quando essa pergunta aparece várias vezes no mesmo dia, o sistema de documentação já está vazando.

Tínhamos acabado de fazer uma rodada de hardening de UX no app. Essa parte virou outro post, sobre rodar uma critique heurística de UX em um jogo React Native. O problema seguinte era menos vistoso, mas igualmente prático: se não conseguíssemos registrar as mudanças com clareza, a próxima release ficaria mais lenta.

A regra: um documento, uma função

A reorganização começou com uma regra simples: cada documento deve responder uma pergunta principal.

Não todas as perguntas. Não todos os detalhes úteis. Uma pergunta principal.

Para este app, as perguntas eram:

• O que está aberto e precisa de ação?
• O que aconteceu em uma data específica?
• O que mudou em uma versão específica do app?
• Qual é a copy estável da loja?
• Como o produto funciona hoje?
• Qual é o gate operacional para Google Play?
• Qual é o passo a passo para publicar?

Essas perguntas não pertencem ao mesmo arquivo.

O erro era tratar “documentação” como um balde só. Quando um projeto sai do desenvolvimento e entra em operação de loja, esse balde começa a receber materiais diferentes: status vivo, fatos históricos, release notes para usuário, referências técnicas e runbooks operacionais. Cada tipo envelhece de um jeito. Cada um será lido por uma versão futura diferente de nós mesmos.

Então separamos por função, não por tema.

A nova estrutura

Depois da limpeza, a documentação do Sudoku ficou assim:

docs/app-sudoku/
  README.md
  SUDOKU_PLANO.md
  SUDOKU_HISTORICO.md
  historico/
    SUDOKU_2026_07_16.md
  releases/
    SUDOKU_0_1_0.md
    SUDOKU_0_1_1.md
    SUDOKU_0_1_2.md
  SUDOKU_LOJA_LISTING.md
  SUDOKU_REFERENCIA_PRODUTO.md
  SUDOKU_GATE_GOOGLE_PLAY.md
  SUDOKU_GUIA_GOOGLE_PLAY.md
  SUDOKU_PLAY_CONSOLE_CHECKLIST.md
  aso/
    SUDOKU_ASO_*.md

É mais arquivo do que antes, mas menos adivinhação. A próxima edição tem um lugar óbvio.

Plano vivo: só o que está vivo

SUDOKU_PLANO.md agora é o plano vivo. Ele não deve acumular hashes de build, logs antigos de validação, referência completa de produto nem histórico detalhado do mês passado.

A função dele é responder: o que é verdade agora, o que ainda está aberto e o que deve acontecer depois?

Mantivemos status, prioridades atuais, itens abertos do gate Google Play, roadmap e riscos. Movemos descrições estáveis de produto e detalhes antigos de gate para outros arquivos.

O teste prático é simples: se um item concluído não muda mais o que devemos fazer depois, provavelmente ele pertence ao histórico ou à referência, não ao plano vivo.

Histórico: um arquivo por data

O changelog antigo era um único Markdown enorme. Ele preservava fatos, mas era ruim de buscar e editar. Transformamos em índice mais arquivos diários:

SUDOKU_HISTORICO.md
historico/SUDOKU_2026_07_16.md

O índice tem uma linha por data. O arquivo diário contém as notas reais.

Mantivemos o nome do app no arquivo (SUDOKU_2026_07_16.md). Só a data pode colidir com outros apps no buscador de arquivos. O prefixo do app deixa a busca útil dentro de um monorepo.

Quando há vários eventos no mesmo dia, não criamos vários arquivos. O arquivo continua sendo um por data, e o sufixo vira heading interno:

# 2026-07-10

## 0.1.0+9

...

## desenvolvimento 0.1.1

...

Isso evita nomes como SUDOKU_2026_07_10_0_1_0_9.md, que são mais difíceis de prever e piores para busca.

Release notes: um arquivo por versão do app

Release note não é a mesma coisa que histórico.

Histórico responde: o que aconteceu nesta data?

Release note responde: o que mudou desde a versão anterior?

Essas respostas podem atravessar datas. Por isso as release notes ficam em releases/, com um arquivo por versão semântica:

releases/SUDOKU_0_1_2.md

No começo tentamos colocar o build Android no nome, como SUDOKU_0_1_2_11.md. Era errado. Google Play e App Store podem divergir. Android usa versionCode; iOS usa buildNumber. Uma rejeição ou reenvio pode mudar uma loja sem mudar a versão semântica do app.

Agora o filename representa a versão do app. Os builds específicos de cada loja ficam dentro do arquivo:

# 0.1.2

## Builds

| Store       | Build          |
| ----------- | -------------- |
| Google Play | versionCode=11 |
| App Store   | TBD            |

Essa decisão evita que uma futura release iOS quebre o padrão de nomes.

Listing da loja: copy estável

SUDOKU_LOJA_LISTING.md tinha virado uma mistura de copy estável da loja e release notes antigas. Removemos as notas inline e deixamos apenas o listing, referências de loja e um índice para os arquivos versionados.

Isso importa porque copy de Play Store e release notes mudam em ritmos diferentes. A descrição longa pode ficar estável por meses. Release notes mudam a cada upload.

A mesma separação ajudou quando trabalhamos na landing pós-lançamento. Esse processo está no post sobre por que reconstruímos a landing page depois do lançamento na Play Store. Copy de loja, copy de landing e release note se conversam, mas não são o mesmo artefato.

Referência de produto: como o app funciona

SUDOKU_REFERENCIA_PRODUTO.md agora guarda contratos estáveis de produto e sistema: features implementadas, direção visual, regras de score, comportamento do Daily Challenge, princípios de animação, contratos de telemetria, ads/privacidade, configurações e checks de qualidade.

Não é backlog. Não é plano de release. É a resposta para: como o produto funciona hoje?

Essa distinção importa. Se um dev futuro quiser entender por que Auto Notes custa créditos ou como funciona a fórmula de score, ele não deveria cavar gates de release nem hashes antigos de AAB.

Gate Google Play: validação sem poluir o plano

SUDOKU_GATE_GOOGLE_PLAY.md guarda o gate operacional detalhado: Play App Signing hashes, histórico de AABs, fatos de validação, referências de smoke e contingências antigas do Play Console.

Parte disso ainda é útil. Nada disso pertence ao plano vivo.

O runbook fica separado em SUDOKU_GUIA_GOOGLE_PLAY.md: esse arquivo diz como publicar. A referência de gate diz o que já foi validado ou precisa de contexto de validação. O checklist do Play Console continua sendo checklist, não diário de status.

As limpezas pequenas que importam

Também removemos um arquivo chamado Pendencias.md. Ele tinha instruções temporárias, um prompt antigo de design, notas de teste manual e uma lista de compras. Era inofensivo até não ser mais. Deixar aquilo em docs/ ensina para contribuições futuras que scratch pertence à documentação do projeto.

Não pertence.

Movemos a pesquisa ASO para uma pasta aso/ com README próprio, mandamos .DS_Store para o lixo e rodamos uma checagem mecânica de links Markdown depois de cada migração. A checagem final nos docs do Sudoku não encontrou links relativos quebrados.

O template que vamos reutilizar

Para o próximo app, esta é a estrutura que começaremos usando em vez de descobri-la no meio da operação de release:

docs/app-name/
  README.md
  APP_PLANO.md
  APP_HISTORICO.md
  historico/
    APP_YYYY_MM_DD.md
  releases/
    APP_X_Y_Z.md
  APP_LOJA_LISTING.md
  APP_REFERENCIA_PRODUTO.md
  APP_GATE_GOOGLE_PLAY.md
  APP_GUIA_GOOGLE_PLAY.md
  APP_PLAY_CONSOLE_CHECKLIST.md
  aso/

Nem todo app precisa de todos esses arquivos no primeiro dia. Mas as funções devem estar claras desde o início.

A lição

Documentação fica difícil de manter quando documentos são nomeados por sensação, não por responsabilidade.

“Plano” vira tudo que ainda não foi categorizado. “Changelog” vira um scroll de fatos. “Listing” vira release notes mais copy de loja. “Checklist” vira status log. Isso funciona até parar de funcionar.

A correção não é escrever menos. É decidir o que cada arquivo pode conter.

A melhor estrutura de documentação é aquela que deixa a próxima edição óbvia a ponto de ser entediante.