Use short design docs for changes that are ambiguous or costly to undo

A design doc is an informal document written before coding begins that describes the high-level approach and, most importantly, the trade-offs considered. Malte Ubl's description of design docs at Google lists their purposes: catching design issues early, building consensus, considering cross-cutting concerns and recording decisions.

Common sections:

• Context and scope: what is being built and the landscape around it.
• Goals and non-goals: non-goals are things that could reasonably be goals but are deliberately excluded.
• The design: the approach, with diagrams, APIs and data storage where relevant.
• Alternatives considered: other approaches and why this one was chosen.
• Cross-cutting concerns: security, privacy and observability.

The same article suggests about 10 to 20 pages for larger projects and a 1 to 3 page mini design doc for smaller changes.