Engineering Design Documents

“Measure twice, cut once”

This proverb captures why I find immense value in writing design documents. It provides an opportunity for early iterations in words that are much easier than the same iterations in code.

Engineering design documents help articulate the decisions and tradeoffs made when building a feature. These decisions and tradeoffs are made with a predefined set of requirements in mind. These requirements often come from a product team.

Some Tips

Iterate

Your first draft is your worst draft. This is a normal part of the journey. Each iteration is about clarifying your thoughts, organizing them and making them more concise. Take breaks and work on one chunk at a time.

Draw

A diagram is worth a thousand words. Any time you are listing a set of steps there might be an opportunity to use a diagram.

Simplify

If you can say the same thing in one sentence vs five sentences do it! This is really helpful for anyone that reviews the document.

Discuss

A design document is a place for healthy constructive conversations. Do not design in a silo. It is perfectly ok to ask for feedback midway.

Question

Writing a good design document involves taking the time to ask questions. It is not a race to a solution.