0001 — Seis níveis de documentação e nomenclatura definitiva¶
Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-11
Contexto¶
O modelo original tinha 4 níveis (pré-projeto, projeto, código, usuário). Ao
aplicá-lo em apps reais, dois furos apareceram: runbooks técnicos do
bi-transporte-xls (deploy, nuke da replicação, google-auth) não cabiam em
nenhum nível — guia é para usuário final, design doc registra decisões, não
procedimentos (brecha reportada pelo loop da constituição §6); e o nível
"código" pressupunha gerador (Javadoc/dartdoc), deixando stacks como Node sem
resposta. Além disso, os nomes design/, rd/ e guias/ eram jargão pouco
claro para quem navega o portal.
Decisão¶
Constituição v0.4.0 passa a ter seis níveis, com pastas autoexplicativas:
| Pasta | Nível | Para |
|---|---|---|
pre-projeto/ |
1 | avaliar a viabilidade do projeto |
projeto/ |
2 | o desenho do projeto, antes de programar |
decisoes/ |
3 | o que foi decidido em cada projeto, e por quê |
dev/ (opcional) + site/api/ |
4 | documentação para devs |
operacao/ |
5 | runbooks para a equipe interna |
manual/ |
6 | manual do usuário final |
Renames: design/ → projeto/, rd/ → decisoes/, guias/ → manual/
(tipos projeto | decisao | dev | operacao | manual). O nível Dev é definido
pela audiência, não pelo formato: onde há gerador, é API reference gerada;
nas demais stacks o doc de projeto cobre interfaces e docs/dev/ fica para
doc escrita à mão (ex. mapa do código). Operação separa operar (runbook,
jargão ok) de usar (manual, sem jargão).
Esta nomenclatura é congelada: foi o último grande rename do padrão.
Consequências¶
- O validador de frontmatter aceita os nomes legados (
design/rd/guias) até a migração oportunista; renomear arquivo publicado exige redirect. - Novo template
runbook.md; templates renomeados (doc-projeto.md,decisao.md,manual-usuario.md). - Repos existentes (ho-scrapper, BIs) migram quando forem tocados.
Alternativas consideradas¶
- Runbooks dentro de
guias/: mistura audiências — guia é sem jargão, runbook pressupõe acesso a infra. Descartado. - Operação como extensão do nível 4 (sem nível novo): esconderia a diferença de audiência na tabela da constituição. Descartado pelo Gustavo.
- Manter os nomes
design/rd/guias: evitava migração, mas perpetuava jargão num portal que não-devs vão navegar. Descartado — melhor renomear agora, com 1 app publicado, do que depois de 10.