minions-ai-agents/antigravity_brain_export/knowledge/documentation_standards.md

📚 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?