Pro-Owner perspective: This document frames your systems as a technical estate — an asset to be stewarded, documented, and bequeathed. Treat these steps as craftsmanship: protect the continuity, auditability, and transferability of your digital legacy.

What it is

A documentation standard enforcing: (1) required sections (What it is, Why it matters, How to use, Failure modes), (2) last-validated dates (docs expire without updates), (3) grading rubric (docs scored 0-100 based on completeness, clarity, examples). Applies to: runbooks, API docs, architecture docs, onboarding guides.

The standard eliminates "tribal knowledge" (undocumented critical procedures known only to one person) and "stale docs" (README last updated 3 years ago, instructions no longer work).

Why it matters

Undocumented systems are unoperatable: when the person who knows how it works is unavailable, systems become mysteries. Stale docs are worse than no docs: they create false confidence ("I followed the README but it didn't work").

Documentation standards make knowledge explicit, transferable, and maintainable. New team members onboard faster. Incidents resolve faster (runbooks exist). Technical debt is visible (gaps in docs = gaps in understanding).

How we do it

1. Required sections (all docs must include):
   • What it is: 2-3 sentences. No jargon. Explain like target audience is smart but unfamiliar.
   • Why it matters: Context. What problem does this solve? What breaks if this doesn't work?
   • How to use: Step-by-step. Include prerequisites, commands, expected outputs. Testable by following instructions.
   • Failure modes: Common errors, troubleshooting steps, escalation paths.
   • Last validated: ISO date (YYYY-MM-DD). Must be within 180 days or doc flagged as stale.
2. Grading rubric (scored 0-100):
   • Completeness (40 points): All required sections present. Examples included. Edge cases documented.
   • Clarity (30 points): Plain language. Scannable (headings, bullet lists). No assumed knowledge.
   • Examples (20 points): Code snippets, screenshots, sample outputs. Real-world usage, not synthetic.
   • Freshness (10 points): Last validated within 90 days (10 pts), 90-180 days (5 pts), 180+ days (0 pts).
3. Enforcement:
   • Pre-commit hook: New/modified docs must include last-validated date.
   • Quarterly review: All docs audited. Stale docs (180+ days) flagged for update or deletion.
   • Doc health dashboard: Coverage (% of systems documented), freshness (avg days since last validation), gaps (undocumented critical paths).

What you receive

• Documentation rubric: Grading system with scoring breakdown (0-100).
• Required sections template: Markdown template with placeholders for all required sections.
• Example docs: Good vs bad comparisons showing what meets standard vs what doesn't.
• Doc health dashboard: Real-time view of documentation coverage, freshness, quality scores.

All docs stored in version control (Git) with last-validated enforcement via pre-commit hooks.

Evidence

Interactive rubric grader:

• Good vs bad snippets: Side-by-side comparison of documentation quality.
  • Bad: "Run the script. It should work." (no context, no example, no failure modes)
  • Good: "Run ./deploy.sh production. Expect 'Deployment complete' within 5 min. If error 'permission denied', check AWS credentials in ~/.aws/credentials."
• Scoring simulation: Type doc content, see rubric score update in real-time. Highlights missing sections, unclear language.
• Required sections checklist: Interactive checklist showing what's present vs missing.
• Last-validated rule: Shows date math: "Last validated 2026-01-27. Next validation due: 2026-07-27 (180 days)."

Download documentation standards package (rubric + templates + examples + pre-commit hooks): [Link]

Failure modes & guardrails

Failure mode: Rubric becomes bureaucracy
Guardrail: 100-point docs not required. 70+ is passing. Focus on completeness + examples, not perfection.

Failure mode: Last-validated ignored
Guardrail: Automated alerts at 150 days. At 180 days, doc marked "STALE" in all references. At 270 days, doc hidden from search.

Failure mode: Documentation debt accumulates
Guardrail: Quarterly doc review required. Undocumented systems flagged in QBR. No new features until critical systems documented.

Failure mode: Examples synthetic (don't reflect reality)
Guardrail: Examples must be copy-pasteable and tested quarterly. If example fails, doc flagged for immediate update.