# 📚 Padrões de Documentação (O Protocolo "Bibliotecário")

**Público:** Arthur Mendes (Docs Gen) & Sherlock Holmes.
**Objetivo:** Se não está escrito, não existe.

> [!CRITICAL]
> **O Mandato Arthur:**
> "Uma funcionalidade sem documentação é apenas um bug que ainda não aconteceu. Escreva para o humano que está cansado, com raiva e consertando isso às 3 da manhã."

## 1. 📂 A Estrutura "Dewey Decimal"

A pasta `docs/` é sagrada. Adira a esta estrutura:
*   `docs/manual_desenvolvimento/`: Como construir/contribuir.
*   `docs/api/`: Specs OpenAPI e Guias de Referência.
*   `docs/ops/`: Runbooks, Guias de Deploy e `incident_reports/`.
*   `docs/architecture/`: As decisões de `dossier_arquitetura.md` (ADRs).

## 2. 📝 Estilo de Escrita (Claro & Conciso)

*   **Língua:** Português (PT-BR) para Docs Internos. Inglês para Comentários de Código.
*   **Tom:** Profissional, Direto, Sem Enrolação.
*   **Formato:** GitHub Flavored Markdown (GFM).

### A Regra "TL;DR"
Todo documento maior que 50 linhas DEVE ter um `## Resumo (TL;DR)` no topo.

## 3. 🤖 Auto-Geração vs. Escrito à Mão

*   **Auto-Gerado:**
    *   Referências de API (Swagger/OpenAPI).
    *   Documentação de Template Zabbix (usando `generate_template_docs.py`).
*   **Escrito à Mão:**
    *   Decisões "Por que" (ADRs).
    *   Post-Mortems.
    *   Tutoriais ("Como adicionar um novo Agente").

## 4. 💀 Post-Mortems (A Caixa Preta)

Quando um incidente ocorre ("Sev1"), um Post-Mortem é OBRIGATÓRIO.
**Template:**
1.  **Linha do Tempo:** O que aconteceu e quando? (UTC).
2.  **Causa Raiz:** O "Porquê" técnico. (5 Porquês).
3.  **Resolução:** Como foi corrigido?
4.  **Prevenção:** IDs de Jira/Tarefa para correções permanentes.

## 5. 🔍 O Checklist de Auditoria do Bibliotecário

Antes de fazer merge de um PR:
- [ ] **Readme:** Atualizei o `README.md` principal se mudei passos de setup?
- [ ] **Novo Arquivo:** Se adicionei `src/novo_modulo.py`, existe um `docs/manual_desenvolvimento/novo_modulo.md`?
- [ ] **Links:** Todos os links relativos `[Tipo Assim](./arquivo.md)` estão funcionando?