May 8th, 2023 How to write a design document By Jeffrey M. Barber

I’m a big fan of writing (as you can tell from my blog of half-baked ideas) as I believe writing is an essential act to have good thinking. The written word is an arena to battle with ideas, so in this post I want to outline my philosophy of writing design documents. This is because I’m designing an intern program, and I will require interns that touch the Adama code base to write a design document. Thus, this document will serve as a cache for that program.

The design document mind-set

As much fun as building is, building within a company has a long term cost and short term risks. The #1 issue in life is trust between people. Trust is the lifeblood of a business. This must be your mind set as the design document is the arena to answer core questions.

The most important and fundamental question to address without explicitly addressing it is ‘Why you?’

Why should the business trust you with the resources to go and build this thing?

This is a question that you can’t address directly. Instead, you have to signal that you (1) know what you are doing, (2) thought about the problem well, and (3) have gained trust of key stakeholders.

Four central aspects of a design document

Signal #1: Attention

The first paragraph should really address Why should I read this design document; this must be written to address business concerns and goals. You ideally should be able to write this in less than four lines, and this is important. It’s so important that you can measure your success by witnessing others leverage these lines in conversation up and across people.

In these four lines, your need to fundamentally answer: Why do we need to do this?

Signal #2: Define objectives

After the first paragraph, people should know the motivation of the problem and be interested to learn more. Here, you have the opportuntity to point people in a direction that you want. Illustrate goals that you want to achieve, and any mechanism to measure goal progress. Goals should speak to a value proposition set up by the attention.

This is now a time to out-out of work by illustrating non-goals, and here the important aspect is illustrate priorities. Illustrating non-goals allows you to signal trust by exercising judgement.

Signal #3: Define the battlefield

Here, is where you provide a tactical map of the battle ahead.

A visualization/diagram/picture is an appropriate way to share here. For example, a diagram of components and their relationships from 50,000 feet is important to lay out the tactical battle. The goal here is to identify the terrain.

For everything element in your visualization, a paragraph is appropriate to answer these questions: What new {area, component, service} are needed to be secured? What existing {area, component, service} need to be fortified or abandoned?

This is your chance to outline your plan at a high level by demonstrating (1) you know the problem, (2) you have done your homework and inventoried existing assets, (3) you know the terrain.

Signal #4: Identify unknowns

With the macro pieces laid out along with their relationships, you now need to identify pitfalls and potential risks. This is an opportunity to stretch your mind across time to signal that you see the bumpy road ahead. Here is where you identify risks and provide tactical guidance to mitigate them.

Prepare: meetings before the meeting

The more junior you are, the less of the battlefield you have within your head. Accept that you are more wrong than right, so have a meeting with a senior technical leader and they will identify their concerns. A key challenge here is to solicit feedback from stakeholders as many problems mirror the blind men and elephant parable. Talking with other leaders and managers is important to get a sense of competing values.

Beyond solving the problem at hand, your task is to align everyone on a path forward. There is nothing worse then having a senior leader who deeply understands the problem space pointing out all the inadequacies in your plan.

The design review

The design review is a chance for all stakeholders and participants to review the plan. This is the go/no-go moment, and ideally a majority are in agreement that the plan is mostly good. Some stakeholders will carve out exceptions for future refinement, but you want them bought in at a high level.

Summary

Ideally, this is a light-weight process because your #1 job isn’t to lay out a waterfall plan. Instead, the design document is a tool for you to illustrate your thinking to both yourself and others. This tool is then important for building trust.

These are the important questions for you to answer from the mindset of the reader:

  • why should I trust you with this problem?
  • why should I care about this proposal?
  • why is this design important to me?
  • what are the major pieces of the design?
  • what are the relationships between the major pieces?
  • what new things do we need to maintain over decades?
  • what old things need to be touched?
  • what old things can we eliminate?
  • how will this person overcome this concern I have?

The key is being ruthlessly honest, and that’s it!