# 📚 Documentation Standards (The "Librarian" Protocol)

**Audience:** Arthur Mendes (Docs Gen) & Sherlock Holmes.
**Objective:** If it's not written down, it doesn't exist.

> [!CRITICAL]
> **The Arthur Mandate:**
> "A feature without documentation is just a bug that hasn't happened yet. Write for the human who is tired, angry, and fixing this at 3 AM."

## 1. 📂 The "Dewey Decimal" Structure

The `docs/` folder is sacred. Adhere to this structure:
*   `docs/manual_desenvolvimento/`: How to build/contribute.
*   `docs/api/`: OpenAPI specs and Reference Guides.
*   `docs/ops/`: Runbooks, Deployment Guides, and `incident_reports/`.
*   `docs/architecture/`: The `dossier_arquitetura.md` decisions (ADRs).

## 2. 📝 Writing Style (Clear & Concise)

*   **Language:** Portuguese (PT-BR) for Internal Docs. English for Code Comments.
*   **Tone:** Professional, Direct, No Fluff.
*   **Format:** GitHub Flavored Markdown (GFM).

### The "TL;DR" Rule
Every document longer than 50 lines MUST have a `## Resumo (TL;DR)` at the top.

## 3. 🤖 Auto-Generation vs. Hand-Written

*   **Auto-Generated:**
    *   API References (Swagger/OpenAPI).
    *   Zabbix Template Documentation (using `generate_template_docs.py`).
*   **Hand-Written:**
    *   "Why" decisions (ADRs).
    *   Post-Mortems.
    *   Tutorials ("How to add a new Agent").

## 4. 💀 Post-Mortems (The Black Box)

When an incident occurs ("Sev1"), a Post-Mortem is MANDATORY.
**Template:**
1.  **Timeline:** What happened and when? (UTC).
2.  **Root Cause:** The technical "Why". (5 Whys).
3.  **Resolution:** How was it fixed?
4.  **Prevention:** Jira/Task IDs for permanent fixes.

## 5. 🔍 The Librarian's Audit Checklist

Before merging a PR:
- [ ] **Readme:** Did I update the main `README.md` if I changed setup steps?
- [ ] **New File:** If I added `src/new_module.py`, is there a `docs/manual_desenvolvimento/new_module.md`?
- [ ] **Links:** Are all relative links `[Like This](./file.md)` working?