7  Documentation Standards

7.0.1 Style & Structure

• Write for future readers: what is their expertise, context, decisions, examples.
• Write with AI to save time and improve formatting, comprehensiveness, and style but respect the readers’ time. Remove superfluous content and verify that what has been written is correct.
• Use headings, tables, and diagrams when helpful; keep docs living and indexed.

7.0.1.1 Additional Pointers:

1. Write top‑down: start with TL;DR, then details.

2. Prefer short sentences, active voice, and concrete examples.

3. If a thread gets long, create a doc and post the link + summary.

7.0.2 Templates (Recommended)

• Proposal/RFC: Problem, options, trade‑offs, decision.

• Runbook: Overview, prerequisites, steps, validation, rollback, contacts.

• Post‑Incident Review: Timeline, root cause, fixes, prevention.

• Test Plan: Scope, fixtures, metrics, pass/fail, sign‑off.

• Coverage Ledger: Requirement → Code/Test/Doc references.

7.0.2.1 Additional Pointers:

1. Keep master templates read‑only; duplicate before editing.

2. Store templates in the shared Templates folder and index them in #resources_documents_links.

3. Keep the templates uniform.

7.0.3 Naming & Versioning

• Files: [Project]_[Topic].md

• Branches: feat/..., fix/..., docs/... with linked issue ID.

• Use PR reviews (≥1 reviewer) and semantic versioning where applicable.

7.0.3.1 Additional Pointers:

1. Use semantic versioning where appropriate (MAJOR.MINOR.PATCH).

2. Maintain a CHANGELOG.md for repos with user‑visible changes.

3. Tag releases and link to release notes in the project README.

7.0.4 Document Entry

• Add quick links to Decision Log, Escalation Path, Open Risks, and Latest Release Notes.

• Use Slack bookmarks for the index, roadmap, and runbook; keep the top 5 links visible.

• On project close, post a Final Handoff (links to docs, owners, and open items) and then archive the channel within 14 days.

• Default: Save recordings to the appropriate project folder within Shared Drive › Recordings.

• Automation: Use the approved automation to move new recordings to the correct folder daily; owners validate weekly.

• Indexing: After each recording, post the link + 1‑line summary in the project Slack channel and add to the project index.

• Check permissions so all project members can view.

7.0.5 Resources Index Channel

• Use #resources_documents_links to post or update: project indexes, specs, SOPs, templates.

• Curate a monthly top‑of‑mind index post linking critical documents.

7.0.5.1 Additional Pointers:

1. Use simple tags like [SOP], [RFC], [Template] at the start of posts.

2. Monthly housekeeping: archive stale links and refresh the index.

3. Assign a rotating curator to keep the channel high‑signal.

7.0.6 Uptime Monitor

• Alerts flow to #uptime-monitor. On alert: acknowledge in thread, consult the Service Runbook, execute mitigation/rollback, post resolution summary, and file a post‑incident review within 24 hours.

7.0.7 Document Etiquette

1. Doc Lifecycle: Draft → In Review → Approved → Deprecated (with successor link). Show status atop the doc.

2. Glossary: Maintain a project glossary; define acronyms on first use and link to the glossary.

3. Diagrams: Store editable source files (e.g., draw.io/Figma) alongside exported images; include version/date.

4. Owners & Review: Each doc lists an owner and “Last reviewed” date; set a review reminder every quarter.

5. Archiving: Move stale docs to an Archive folder with a pointer from the index to the current source.

6. Images & Redaction: Blur/redact secrets and PII before sharing screenshots, if shared externally.