Pular para o conteúdo principal

Documentation Standard

Regra central: Markdown + Git = source of truth. Docusaurus é interface de leitura. Um assunto = um documento canônico.

1. Quando criar um documento​

Crie um documento somente quando todas as condições forem verdadeiras:

  1. A informação precisa sobreviver ao chat/sessão em que nasceu.
  2. Não existe documento canônico que já responda a mesma pergunta.
  3. Existe um owner disposto a mantê-lo.

Não crie documento para: rascunho de raciocínio, decisão ainda não tomada, conteúdo que pertence a um documento existente (edite o existente), ou duplicação "para facilitar" (link, nunca cópia).

2. Frontmatter obrigatório​

Todo documento em docs/ começa com:

---
title: "Nome do documento"
description: "Uma frase que responde: que pergunta este documento responde?"
owner: "Founder / Régua"
status: DRAFT | REVIEW | APPROVED | SUPERSEDED | ARCHIVED
version: "1.0"
last_reviewed: 2026-09-17
canonical: true | false
document_type: institutional | method | governance | procedure | standard | template | runbook | decision | guide
---

Regras:

  • title e owner nunca podem faltar.
  • status: APPROVED exige version definida e aprovação humana registrada (commit ou decisão).
  • canonical: true significa: esta é A resposta oficial para o assunto. Só pode existir um documento canônico por assunto.
  • last_reviewed é atualizado a cada revisão real de conteúdo — não a cada typo.
  • Não adicionar campos novos sem função clara (ver Governance Index, regra de mudança).

3. Estrutura mínima​

  1. Um único H1 (#) — igual ou equivalente ao title.
  2. Seções em H2 (##); subseções em H3 (###). Não pular níveis.
  3. Primeira linha após o título: a que o documento serve (1–3 frases).
  4. Documento que define regra usa linguagem normativa: deve / não pode / é proibido — não "idealmente", "talvez", "seria bom".
  • Links internos: relativos ao arquivo (../03-governance/governance-index.md) — nunca URL absoluta do site.
  • Link quebrado é falha de build (npm run docs:check).
  • Referenciar, nunca duplicar: se outro documento já define algo, linke.

5. Tabelas​

Usar tabelas para dados enumeráveis (status, tokens, fontes canônicas). Explicação vai em prosa antes ou depois — não dentro da célula.

6. UNKNOWN​

Quando um fato necessário não está estabelecido, escrever explicitamente UNKNOWN no documento — nunca inventar. Ver regra 7 do Governance Index.

UNKNOWN > certeza inventada.

7. Evidência e referência​

Afirmações materiais (métricas, resultados, "funciona", "PASS") devem apontar evidência: link para Evidence Pack, issue do Linear, log, medição. "Alguém disse" não é evidência.

8. Linguagem​

  • Idioma padrão da biblioteca: português para documentos institucionais e guias; documentos de governança existentes em inglês permanecem em inglês (não traduzir silenciosamente).
  • Frases curtas. Voz ativa. Sem jargão decorativo.
  • Termos com significado fixo (PLANNED, DONE, UNKNOWN, GATE, VERIFIED…) não são traduzidos nem parafraseados.

9. O que este standard NÃO exige​

Sem aprovação em comitê, sem processo pesado, sem burocracia para corrigir typo. SIMPLES > SOFISTICADO. Correções triviais podem ser feitas direto — as regras existem para conteúdo, estado e verdade, não para atrito.