Programming/Design Docs

What is a Design Document?

Amazon is known for being a bit weird for many reasons, but one of the reasons is Amazonians are prohibited from using PowerPoints or slide decks. Any transfer of information is expected to be written in a document. Instead of the meeting host giving a presentation, meetings start with time reserved for attendees to read the prepared document. Amazonians have names for each of these types of documents: some are familiar, such as Press Releases, and some are more Amazon-specific such as the One Pager. The document software developers write to convey their technological solutions to a given problem are called Design Documents, or design docs for short.

What is the General Structure of a Design Document?

The goal of a design document is to cover the entire solution in a way an outsider with little-to-no knowledge of your problem can understand the following:

• what problem you are trying to solve,
• how you are planning on solving it,
• and why you chose this solution over others.

Design document formats vary widely: a design document can be a word document, a wiki page, or a Markdown file, and it can be broken down in many different ways. I have found that starting with the following sections helps me consider all the data needed to form a complete solution:

• Problem Statement,
• Requirements,
• Out of Scope,
• Tenets,
• Success Criteria and Metrics,
• Proposed Solution,
  • Low-Level Design,
  • Architecture Diagram,
  • Technology Decisions,
  • Testing Strategy,
  • Risks,
• FAQ,
• and Appendix.

I want to highlight the word "starting." I generally start with all of these sections, but I don't always end with all of them. For example, I often omit the FAQ. When I receive a question at any part of the design document process, I try to answer that question in the appropriate section. Additionally, the questions I receive don't often repeat themselves, so the "frequently" part of FAQ doesn't come up either. As another example, I generally cover the alternatives of my technological choices in the Technology section. If the solution becomes very complex or requires extensive testing and prototyping of other solutions, these may be broken into an Alternate Solutions or Considered Technology section.

Suggestions and Best Practices

1. Read about each section before writing a design doc. It helps to have the full picture before starting.
2. Complete at least the Problem Statement, Requirements, and Tenets section and get some sort of approval (formal or informal, either from management or the client), before starting on the Proposed Solution. The final design review will go a lot smoother if everyone is on the same page about what the problem is, what is necessary to solve the problem, and what to prioritize when making design trade-off decisions.
3. Prototype, prototype, prototype. Not sure if something will work? Spend time making a proof of concept. Nothing more frustrating and embarrassing than getting buy-in on a solution that doesn't work in practice.