Documentation and ADRs

Records decisions and documents the why — context, constraints, trade-offs, and rejected alternatives that code alone cannot express.

Overview

Code tells you what was built. Documentation tells you why it was built that way, what alternatives were rejected, and what constraints governed the decision. The most valuable documentation captures the reasoning, not the mechanics.

This skill covers four documentation layers, from most to least strategic:

Layer	What	When	Effort
🏛️ ADRs	Architecture Decision Records — capture why a decision was made	Every significant architectural choice	10-30 min
📘 README	Project entry point — what, why, how	New projects, major releases	15-60 min
🔌 API Docs	Endpoint/schema documentation	Every public API change	Per-endpoint
📝 Inline Docs	Comments explaining why, not what	Continuously	Seconds

documentation-and-adrs

Documentation and ADRs

Overview