Design Document 101

Over a course of my career my attitude was changing towards design documents, from seeing them as a waste of time to recognizing them as tools for being right. In this article, I want to explain why and how I write these documents.

Most of information here will be useful for broad general public.

Why?

So why do I write design documents? To meet a project objective in a right quality and in a right time.

I always faced with a degree of ambiguity in projects. For example, I don’t have all requirements, required knowledge, a goal is not clear, obstacles are not yet obvious and solutions are blurry. It’s hard to be right in these circumstances. That’s when I write.

Because of writing, I am forced to think clearly about a project, its problem, solutions, what I know and what I don’t know, what is important and what is not. Try to write without a clear understanding and your narrative won’t be coherent. Ability to write a coherent narrative on a subject is a litmus test whether you think clearly about it.

Also because of writing, I can share my thoughts with many others in asynchronous fashion and find out where I’m wrong. Yes, I become more right by actively looking where I’m wrong.

Another fun litmus test: if you cannot explain something to a seven years old kid you don’t understand it completely (in other words, all things are simple in the world, our lack of understanding makes them to be seen complex).

Below I give you an example of what I write and how I write in a design document so you can walk off with some practical knowledge.

Start with Audience

My audience is myself by default. And others who will be affected by a project or know about the project. Others are an important source of feedback on what I don’t know and where I’m wrong.

The audience defines a language for a document, a level of details per a particular area.

Also remember, that bigger and more different an audience is, harder and longer it takes to write a document.

For trade off, at the beginning, I do not try to nail down a document to be ready for all possible audiences which will review it down a line. I start with the smallest audience, for example, an immediate team and update the document as more people are involved and more feedback is received.

Title

A title is the first thing which is seen when people open your document. If they don’t get it, they may pass by the document, be disengaged or indifferent. Remember the “Why?” ? Indifferent audience does not provide valuable feedback.

I choose a title which describes what is a final value will be created.

Goal

A design document aims to the fundamental goal: to share a thought process and collect feedback. I restate the goal to an audience at the beginning of every document to remind it again (don’t worry, good things like a “good morning” can be told every day).

Background

Not everyone will share the same knowledge about the problem I need to solve. Lack of context will lead to indifference, indifference will lead to lack of feedback. I provide an applicable context and information so everyone in audience can reason about the rest of the document.

Problem statement

This is one of the most important section. I answer these questions here:

1. Why it’s a problem
2. Why do we need to solve it now
3. What will happen if we don’t solve it at all

It gives perspective of urgency, priority and whether it’s a good use of time and resources for an audience to review.

Functional Requirements (Use Cases)

The problem statement will not be complete and specific without requirements. I split requirements into two buckets: functional and non-functional.

Functional requirements describe what needs to be done, they are use cases.

I describe in very specific manner what the system has to do, broken down to a separate cases. For example, for a browser url shortener service (like https://bitly.com), requirements may be:

Requirement 1: Shorten an url. Accept an arbitrary url (AU) from a user and return a unique shortened version of the url (SU).

Requirement 2: Use the shorten url. Accept a previously shortened version from a user (SU) and redirect to an original url (AU).

Non Functional Requirements

Non functional requirements describe how it needs to be done. For example, for the above url shortener service, I can write down such requirements:

1. Use https
2. Perform use cases in less than 1 second
3. The shortened version of url can be used immediately after it was shortened

It does not really change a value of the service per se (e.g. 3 seconds vs 1 second) but it can affect the service usability greatly.

Assumptions

The difference between an assumption and a fact is that assumption is not proven by data for you or your audience at the moment. It’s ok to have assumptions where it makes sense. I apply a judgment where to use assumptions (because it’s good enough) and where to rely on facts (because it’s really important).

I thought that my audience (like my team) shared same assumptions with me. It turned out to not always be true. A reader of a document may have a different assumption on a same topic which can create a heated debate and reduce a signal to noise ratio.

To be transparent, explicit and avoid misunderstanding, I write down main assumptions (if any) as a separate section. I always call out any other assumption in the document.

Open questions

Not always I have a full clarity of a design or problem when I start writing a document. Though it does not prevent me from sending this document to review by others and gain invaluable insights sooner. Any ambiguity or lack of information can be put in a section of open questions. It will allow to keep track what is still not clear and some of the readers can provide answers.

Solution

To the moment, we were working on a background, a problem statement, requirements, why it’s important, what we know and what we don’t know.

It’s time to write down a solution to the problem. Solution are very specific to specific problems so I will not focus on how to solve problems. Instead I will focus on how I present solutions.

Options

I always evaluate more than one option. It gives a perspective on a solution in favor. It shows to an audience what else I considered to come up with the solution. I provide each option with a brief description, pros (upside/+) and cons (downside/-). Pros and cons are relative to a context and problem being solved.

Remember, there is no bad option, instead there is not a right option for the given problem.

I love when an audience provides with new options.

Recommendation

Some authors tend to provide options but do not choose one as a recommendation because they are not sure which one is right. It puts the design in status quo and halts progress. At the end of the day, it’s ok to make a wrong call. The wrong call will remove a status quo and engage an audience. The wrong call is still a decision which is better than an indecision.

How do I choose an option to recommend? I recommend an option where pros outweighs cons and explain how the cons will be mitigated.

Appendices

Documents sometimes require a lot of details and data to validate them. Though all of this data is not needed as a part of narrative to make a point. All lengthy data, tables and code can go to a bottom (“appendicies”), and referred to through out the document.

Executive summary

By this moment, we have a problem, the options to solve it and recommendations. Woo-hoo! We are ready to present the design to our teams!

At the stage I reflect and squeeze all this into a short executive summary and put it right after a title. The executive summary along with a title helps audience if the document worthy to read and what sections to pay attention to.

Extra tips

Some extra tips to writing:

1. To make an informed decision, do not use adjectives, use data (“big” == “90% in comparison to X”, “a lot of money” = “$1,000”)
2. Remove all extra words which do not add meaning (“I think that this is the the option we need to go with because…” = “This is the recommended option because…”)
3. Use numbered lists instead of bullet lists (see extra tip #3)
4. Use an active voice and specific actors where possible (“url shortener will be build” vs “our team will build the url shortener”)

Summary

I gave you a perspective to rethink your attitude towards design documents and techniques on how to write them effectively. I recommend to put the reading into action next time you have a new project. Remember, practice makes master.

Next, I will publish an article on how run a review session for your document to get the most of value out of it.

A note In Plain English

Did you know that we have four publications and a YouTube channel? You can find all of this from our homepage at plainenglish.io — show some love by giving our publications a follow and subscribing to our YouTube channel!