Pular para conteúdo

Constituição da Documentação X-Adm

Documento curto e estável. Define o que documentamos, para quem e qual o mínimo. Templates, toolchain e automações derivam daqui. Se algo conflita com este documento, este vence.

1. Princípios

  1. Documentação perto do código. A doc mora no docs/ do repositório do próprio projeto e muda no mesmo PR que muda o comportamento. Doc longe do código morre.
  2. Documentar interfaces, decisões e uso — não o código. O código já diz o quê. A doc serve para por quê (decisões), como integrar (contratos) e como usar (quem não escreveu). O que dá pra inferir do código não vai pra doc — vira mentira.
  3. Docs as code. Markdown versionado no Git é a fonte da verdade. Site (HTML) e Word/PDF são gerados, nunca editados à mão nem commitados.
  4. Decisão é registro; referência é viva. Um RD ou design doc é um retrato datado: não se reescreve, supera-se com outro. Já guias e API reference têm um responsavel: e precisam refletir a realidade — referência desatualizada é bug.
  5. Enxuto por padrão. Design docs curtos; RDs de ~1 página. Seção vazia não existe — ou tem conteúdo útil, ou não está no documento.
  6. Migração oportunista. Não se migra doc legada por migrar; só o que está sendo tocado. Projeto novo já nasce no padrão.
  7. Pronto para IA sem esforço extra. Slug do arquivo é ID público estável (não renomear sem redirect), cada ## responde uma pergunta única, vocabulário controlado. É o mesmo trabalho que deixa a doc boa pra humano — e viabiliza o futuro RAG/chatbot no ERP.
  8. Português do Brasil em toda a documentação.

2. Os quatro níveis

Nível Conteúdo Audiência Onde vive Formato
1. Pré-projeto business case: go / no-go diretoria fora do Git (por enquanto) Word, template X-Adm
2. Projeto design docs + RDs quem implementa hoje e quem mantém em 5 anos docs/design/ e docs/rd/ do repo do app Markdown + Mermaid + frontmatter
3. Código API reference dev de manutenção comentários no fonte Javadoc / dartdoc, gerados no CI
4. Usuário/suporte guias passo a passo com prints usuário final e suporte docs/guias/ do repo do app Markdown, imagens em docs/img/

Conteúdo mínimo por nível:

  • Pré-projeto: problema do cliente em 1 frase; nº de clientes impactados; esforço em faixa (S/M/L/XL, não em horas); riscos; alternativas consideradas; recomendação. 3 a 6 páginas — não é TCC.
  • Design doc: contexto e escopo (com o que está fora); modelo de dados (Mermaid ER); fluxos principais; resumo das decisões (corpo nos RDs); riscos. Um arquivo por feature/projeto. Não colocar: o que muda toda semana, passo a passo de usuário.
  • RD (Registro de Decisão): Contexto · Decisão · Consequências · Alternativas consideradas. ~1 página: "decidimos X porque Y, considerando Z". Um RD aceito não se reescreve — é superado por outro.
  • API reference: documentar interfaces (o que expõe, recebe, mexe) e chamadas cruzadas (chama X, é chamado por Y). Não colocar comentário que repete o nome da função.
  • Guia de usuário: passo a passo, screenshots, "quando der esse erro, faça isso". Sem jargão técnico, sem nome de tabela.

Transversal (vive no repo central documentacao): esta constituição, templates, glossário de negócio, documentação da infraestrutura Coolify/Forgejo/Traefik e o site MkDocs que publica tudo.

3. Estrutura padrão de cada repo de aplicação

meu-app/
├── README.md                  # o que é, como rodar, como buildar
├── docs/
│   ├── index.md               # visão geral do app
│   ├── design/                # design docs (PROJ-AAAA-NNN-titulo.md)
│   ├── rd/                    # 0001-titulo-da-decisao.md
│   ├── guias/                 # doc de usuário/suporte
│   └── img/                   # screenshots
├── src/                       # Javadoc/dartdoc nos comentários
└── .forgejo/workflows/docs.yml

4. Frontmatter obrigatório (design docs, RDs e guias)

---
titulo: "..."
tipo: design | rd | guia
status: rascunho | em-revisao | aprovado | obsoleto
responsavel: "nome"        # dono do documento — campo OBRIGATÓRIO
modulo: "..."              # ex. combustiveis, transporte, integracao
cliente: "..."             # opcional, ex. OnPetro, Sulplata
atualizado: AAAA-MM-DD
tags: [...]
---
  • Em RDs superados, marcar status: obsoleto e acrescentar superado-por: NNNN.
  • modulo é enum fechado: combustiveis | transporte | fiscal | financeiro | estoque | compras | vendas | integracao | comum (novo módulo = PR neste repo).

5. Convenções

  • Projetos: PROJ-AAAA-NNN (ex.: PROJ-2026-001); o design doc leva o código no nome do arquivo.
  • RDs: NNNN-titulo-curto.md, numeração sequencial por repo.
  • Slugs estáveis: o nome do arquivo é o ID público da página — não renomear sem redirect (quebra busca, links e o futuro RAG).
  • Diagramas: Mermaid inline; PlantUML (.puml) só quando o Mermaid não dá conta. Comitar a fonte do diagrama, nunca o SVG/PNG renderizado.
  • Glossário: cada repositório define em docs/glossario.md o vocabulário do seu domínio (o repo da plataforma define os termos da plataforma; um app de transporte, os termos de transporte que usa). Não duplicar termo de outro glossário — linkar.

6. Governança

  • Por documento: o responsavel: do frontmatter responde pelo conteúdo. Doc sem responsável não chega a aprovado.
  • No PR: mudou contrato, schema ou fluxo público → a doc correspondente muda no mesmo PR. Revisão de doc é parte do code review.
  • No projeto: o checklist de conclusão cobra "documentação atualizada".
  • No CI: validação de frontmatter (campos obrigatórios e enums de tipo, status, modulo).
  • Evolução futura (não implementar agora): bot de frescor, dashboard de saúde da doc, evals de qualidade do RAG.

7. Política de IA

  • IA (Claude ou qualquer outra) nunca lê, copia ou recebe fonte ZIM do ERP. O veto da direção é explícito.
  • IA só opera em repos de aplicação Java/Flutter com autorização prévia da direção, caso a caso.
  • Documentação de usuário, design docs, templates, CI e infraestrutura não são fonte proprietário — IA pode trabalhar livremente.