✍️ Escrevendo Documentação

A documentação do PAEBIRU é a “memória externa” do organismo. Ela deve ser tão rigorosa quanto o código, seguindo convenções estritas para garantir que seja útil tanto para humanos quanto para agentes de IA.

1. Onde Documentar?

Documentação Local: Comentários /// (RustDoc) no código. Explique o porquê, não o quê.
Documentação Transversal: Vive em docs/src/. Use para arquitetura, teoria, guias e runbooks.
README.md: Cada crate deve ter um README descrevendo apenas seu escopo local.

2. Convenções de Estilo

Idioma: Português Brasileiro (pt-BR) é o padrão. Termos técnicos canônicos (ex: Maturidade Causal) devem ser preservados.
Nomenclatura: Arquivos .md usam kebab-case (ex: meu-novo-guia.md).
Links: Use sempre caminhos relativos (ex: ../architecture/kernel.md). Links absolutos quebram o build.

3. Metadados e Cabeçalhos

Não use YAML frontmatter. O mdBook renderiza YAML como texto visível. Em vez disso, use comentários HTML no topo do arquivo:

<!-- title: Título da Página -->
<!-- audience: novos desenvolvedores -->
<!-- status: DRAFT -->

4. Diagramas (Mermaid)

Prefira diagramas code-first usando Mermaid.js. Eles são fáceis de versionar e eficientes para LLMs processarem.

graph TD;
    A-->B;
    A-->C;

5. Checklist de Documentação

O arquivo usa kebab-case?
Os links são todos relativos?
O metadado está em comentários HTML?
Usei o Dicionário para termos técnicos?
Adicionei a nova página ao SUMMARY.md?

Keyboard shortcuts