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

1. 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.