Writing Technical Design Docs

A design doc is a decision artifact, not a specification. Its job is to align people on a direction with enough rigor that work can start and enough humility that the plan can change. Aim for directionally correct, not perfect: a 60% draft circulated now gets better feedback than a 95% draft circulated in three weeks. If the doc takes longer to write than the first slice of implementation, it is over-engineered.

Principles