52 lines
1.9 KiB
Markdown
52 lines
1.9 KiB
Markdown
# 📚 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?
|