Why You Want to Write a Design Document

Why it’s needed

Creating design documents doesn’t sound as sexy as brainstorming or ideation. Some may argue that it’s contradictory to being agile. However, creating a design document can often benefit teams, especially when creating a new product or feature.

In my observation, most teams have the know-how for development and delivery once the problem and scope are clarified. The challenge is the beginning – discovery and definition process. Validating a problem, shaping a hypothesis, and selecting a solution can be often murky for multiple reasons.

• One problem is connected with other problems
• There are multiple solutions to one problem
• A lot of teams have constant pressure to deliver quickly without rationalizing (“we just do it now and change it later.”)

While moving fast is important, just doing it will not only waste resources but also deteriorate user experience in the long run.

How to Structure

Let’s say your team agrees to have a more organized discovery process. What could a design documentation offer? It provides a checkpoint for team members to organize thoughts.

The purpose of these documents is to validate problems, articulate solutions, and record key decisions made, together with Product, Design, and Engineering. This concise document can exist between high-level product requirements and user stories. It is a place to explain a design solution as well as user research, and testing to back it up. Technical feasibility is also tested in this document. Product, Engineering, and Design arrive at the sweet spot before user stories are refined.

This is how I usually structure my design document. Each organization has its own ways of documenting this process. The problem section is often owned by product managers.

1, Problem

• A clear description of a problem with tangible evidence. (e.g. 85% of clients in the pipeline wish to have this feature because…)
• Relationship with other features (e.g. creating this feature means a new widget can be developed in the dashboard..)
• Real-life use cases, for example, from user interviews

2. Hypothesis

Remember we are proposing a solution, which requires a plan to validate it.
“We believe that [building this solution][for these people] will achieve [this benefit or value].
We will know we are successful based on [indicators, metrics, feedback,….].

3. Proposed Solution

• High-level feature description
• User flow (often with wireframes)
• Link to Prototypes, or attached screen design – Obviously, the user flow mentioned above should be the basis for prototype flow
• What’s in scope & out of scope

4. Limitations & Future Ideas

• Limitations discussed in the proposed solution
• Ideas for future improvements

*Additional sections

• Acknowledgment by Engineering, Product, Design
• Document revision history
• Terms and definitions

Here are my tips

• Keep the words short and simple – No one has time to read verbose essays. Keep the point straight and use bullet points and numbers as much as possible. 
• Tell a consistent story verbally, and visually – use one linear story to explain the problem, user flow, and prototypes. Then, be prepared to explain unhappy paths or edge cases.
• Make it easier to manage – Provide major revision history to keep the track of changes. Use consistent terms, naming conventions and folder structure

How to Use

Separate Exploration from Solution when needed

If the problem is complex or somewhat unclear, it’s possible to create an exploratory document first. Exploratory documents can include discussions to clarify problems, research, and multiple solution ideas. The key is to include a rationale for why a specific solution was chosen. Then, link it to the design document to provide context.

Let team members contribute to the design documents 

As more people interact with the solution, technical limitations and UX issues can become more visible. Interesting ideas can be proposed. Open up the document and let others contribute. Listen to other members’ ideas while owning the decision-making process for design. This might be helpful to build positive relationships with Product and Engineering.

Use the document to improve productivity

A design document can be linked with epics or user stories, providing a big picture to the team members. This means that sharing a design document can often reduce redundant conversations. If any team members are lost or simply new to the project, kindly refer him/her to the design document to set the baseline.

Final Notes

I am sure some agile masters may not agree with the notion of design documentation. The point of this documentation is to be more intentional for user experience design. It’s about thinking deeper one more time before jumping into doing, which is essential for user-centered products.