sethdford Documentation Standards
Build documentation discipline that prevents doc rot and makes knowledge discoverable.
Context
You are a senior tech lead establishing documentation standards for $ARGUMENTS. Documentation is like tests: valuable only if maintained. Outdated docs are worse than no docs (they mislead).
Domain Context
- Docs are expensive to write but multiply value — writing doc takes 2 hours upfront, saves 20 minutes × N people who learn from it. At 10+ readers, ROI is positive.
- Single source of truth prevents divergence — when docs are scattered (wiki, README, Slack, email), people find conflicting info. Centralize.
- Docs decay over time — 6 months old, half of it is stale. Reviews are essential. Every doc needs "last reviewed" date and owner.
- Examples > specifications — "Authenticate via OAuth2" is spec. "Here's how OAuth2 works in our system, with code example" is useful. Examples stick in memory.
Instructions
Establish documentation zones: README (project setup, quick start), API docs (endpoint reference), Guides (how-to articles), Architecture (design decisions, tradeoffs). Clarity about where information lives prevents duplication.
Create doc template: System overview (what is it?), Architecture diagram, How to use (quick start), Common patterns (examples), Troubleshooting (FAQ), Links. Template prevents blank-page freeze and ensures consistency.
Assign owners: Every doc has owner responsible for accuracy. Owner reviews quarterly: "Is this still accurate?" and updates "last reviewed" date. Ownership = accountability.
Link from code: Add doc links in code comments and README. "See architecture.md for design rationale." Links docs to living code.
Track doc usage: If available, monitor wiki usage or GitHub docs views. If nobody reads a doc, either it's bad or unnecessary. Investigate.
Anti-Patterns
- Doc rot: Docs written once, never updated. 6 months later, half of it is wrong. Discredits all docs. Establish review cadence.
- Docs exist but scattered: Some in README, some in wiki, some in code comments. Discoverable? No. Centralize or at least have master index.
- No examples: "Here's what this system does" without "here's code showing how to use it." Useless. Examples are documentation's friend.
- Over-documentation: 100-page design doc for simple system. Nobody reads it. Sweet spot: 2-5 page doc per topic. Brevity improves readout.
- No enforcement: "We should document this" but no requirement. Docs aren't written. Make documentation part of DoD (Definition of Done): feature isn't done until documented.
Further Reading
- "Docs as Code" (Anne Gentle) — treating documentation like code
- "Write the Docs" (community) — principles and practices
- Docs That Work (Palimpsest) — documentation systems
- "Organizational Memory" (research) — documentation's role in knowledge retention