How to write an effective design document

Purpose

  • Get buy-in for the high-level architecture from relevant stakeholders (engineering managers, technical leaders, engineers from other relevant groups).
  • Provide a blueprint for implementation.
  • Provide documentation (for historical reference, onboarding etc.)

Audience

  • People who need to approve/provide feedback on the design.
  • People who need to do the work outlined in the document.
  • The author (you’re not going to remember why you did any of this in a couple of months).
  • Internal readers who already know the background whose memory just needs to be refreshed.
  • External readers or newcomers who have no or close to no context and need a high level overview of what this document will cover.

Intro

Technicalities

  • Document status: WIP / Under review / Approved / Implemented / Cancelled
  • Author(s) / DRIs / Owners
  • Last update date
  • Requested review date
  • Approvers list
  • If they’ve been called in for a specific purpose, i.e. security or legal review, point them in the direction of the relevant section using a direct link. They shouldn’t have to read about your APIs if all they care about is the retention policy of your user’s information.
  • Not everyone carries equal weight. Clearly mark which approvers are required and which are optional.
  • Set a date for the review. People are busy, they have to prioritize their work. If you leave things open-ended and depend on people’s good will, they may not get around to reviewing your document. Be respectful, give them enough time to complete the review, but also feel free to nudge them as the deadline approaches. You may escalate or move ahead without their approval if they don’t provide timely feedback. The show must go on.

References

  • Requirements documents
  • Related design documents
  • Marketing or user research
  • Meeting notes
  • and more.

Non-goals / out of scope:

High level architecture

Detailed design

  • APIs
  • Pseudo code
  • Class structure
  • Database schema
  • Specific technology stacks
  • And more

Decisions and tradeoffs

  1. You won’t be able to make any progress on your design until you get everyone’s approval on every small decision.
  2. People have opinions on everything, so you’ll end up wasting a lot of time discussing things that don’t matter much or are obviously the right way to go.

Other stuff

  • Testing strategy
  • Documentation
  • Monitoring and analytics
  • Performance and scale
  • Legal & Security
  • Product lifecycle concerns: e.g. what happens when a user joins/leaves, when a customer is upgraded/downgraded etc.
  • Release plan: feature gating, A/B testing, migration etc.
  • And more.

--

--

--

Tech Lead @ Google • Ex-Dropbox • I create software by applying careful study, thoughtful listening and open conversation

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

UX Design Fitness App — Capstone

Power of Visualization | Aaron Dungca

Geometric Seamless Pattern Constructor — Figma

Vita | Case study

Learn how to add a “Copy Link to Clipboard” button to your website in 10 lines of code

Adding an In-Flight Feature to the Icelandair App ✈️

Boundless Design: Pushing the Limits of Innovation

All about Awning Windows — Seattle, WA

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Rina Artstain

Rina Artstain

Tech Lead @ Google • Ex-Dropbox • I create software by applying careful study, thoughtful listening and open conversation

More from Medium

Engineering Timelines as a Software Engineer: Time Estimation

New To Scrum? Here Are Some Tips

A small whiteboard with the word Scrum written in blue, three green checkboxes with green checkmarks and next to each checkbox is a red question mark, totaling three question marks. This sits on top of a metal laptop and a black keyboard, which are all on top of a wooden desktop.

To grow as an engineer keep risking failure

A day in the life of a TUI Musement Software Engineer