Design doc
A document written before building something big: the problem, goals, non-goals, proposal, alternatives and risks.
Moving a wall on a drawing costs an eraser. Moving it in a finished house costs a fortune. Before building something big, write a design doc: context and the problem; goals and non-goals (what you're deliberately not doing); the proposal; alternatives considered and why not; risks; rollout plan; open questions. It's cheaper to change a document than a system, and reviewers can catch problems early.
Try it now
The diff shows what changed. The message is for why.
Learn it properly
Writing for engineers · READMEs, design docs, commit messages and bug reports people can act on. About 35 minutes.
Other terms from the same lesson
- architecture decision record: A short note of one significant decision: its context, the decision and its consequences.
- imperative mood: Writing as a command, such as "Add retries". The convention for commit message subjects.
Never trained an AI?
Teach a small one to write, right in your browser. It takes about 20 seconds and needs no account.