The magic missing link: design documentation
By: Addie Johnson
Tags: Product Design, Design, Product, Design Thinking, Documentation

The magic missing link: design documentation

Illustration by Kate Mango

When I was studying graphic design in college, there was always one thing required from every student at the end of the year — the process book. It was easy to tell which process books were scrapped together moments before the deadline. (Trust me, I tried once. My professors were not so impressed.)

It was in those developing years that I learned the importance and emphasis on process work as a way to help conceptualize patterns, relationships, and visual systems. Process made us diagnose the real design problems before we jumped into visual solutions.

Sound familiar?

Modern-day product designers encounter a multitude of problems from a wide range of reasons: outdated codebases, APIs returning invalid content types when there is an error or even disjointed teams within the company. Maybe there’s a customer complaint and there’s a cross-company confusion. Any of these small or large problems often create even larger problems that require a team to look holistically and specifically to more tangibly understand the problem(s) before running to look for solutions.

One of my biggest mistakes in my first product design job was not not asking the right questions, but actually keeping track of the questions I was asking. Our team didn’t write down the multiple directions we explored.

This led me to start to think: why did a certain solution do better than another? Where did all my research links go? (Probably a random Google doc now floating in the big bad internet ether… Oops) How did we go about receiving that group feedback from the consumer insights report? Where did those notes go? How did we communicate this to the rest of R&D? Didn’t you have some other final prototypes that didn’t make the initial first cut?

Enter design documentation.

Why should I use a design document?

Writing down your thoughts is especially important towards the beginning of the design process. Comprehensively outlining what the problem is and why it exists, connecting research with analytics findings, jobs to be done, and design goals help us understand the problem’s complexity and builds out a foundation from which to progress from.

An added benefit — if you’re working with a team, you might even be continuously editing yourself to make things as succinct and satisfactory as possible. You probably won’t be randomly rambling when you know this document will be simultaneously watched by others.

Solutions can be tangential, and product designers use a variety of mediums in order to communicate them: words, wireframes, diagrams, low fidelity, and high fidelity prototypes, simple static images or videos detailing complex interactions, code, etcetera. And although designers utilize all these resources, it’s crucial to centralize them in one space to be viewed holistically.

Notebooks are awesome for on the fly idea-generation, and documentation helps us distill that.

Even if process is the act of re-applying specific strategies to different problems, things never go according to plan. Crits or discussions with engineering may impact your initial direction. The doc allows you to keep track of all these meetings and subsequent changes. A clear source of truth that you can always point to. This becomes incredibly important for larger projects, where it’s often hard for yourself and others to remember specific decisions made weeks ago that are responsible for the solution they are seeing today.

Photo by Austin Distel on Unsplash

Benefits for the team

A good design doc doesn’t help just you conceptualize your work — it helps your whole team. Groups that focus on using documentation as a core part of their process make colleagues’ lives incredibly easier when it comes to the overall understanding and staying on the same page. It can be frustrating to attempt to understand what your peers are working on, especially when their decisions could significantly change or affect your projects.

I’m totally guilty of sending important user research interview summaries and affinity diagrams through Slack. I’ve also made extended notes in Sketch files, only to be completely unable to remember where I put Joe’s feedback: was it roughdraftprocess_1 or roughdraftprocess_1B? Ever since prioritizing documentation, I’ve been able to find exactly what I was looking for in a quarter of the time it used to take me previously.

Many designers pride themselves on their tools, and I’m no different. I personally use Notion for overall design documentation and note-taking. It’s beautiful and makes writing up test cases actually kind of fun. It’s super-fast, too. I also like Evernote and Hugo. I’m also not not afraid of Google Docs, as long as everything is condensed and organized into ALL the folders.

Hitting your stride and structure

During my time at GSK as a user experience designer, I practiced and refined a specific design process when tackling complex problems.

Here is my overall outline:

1: Introduction

This should describe the purpose of the document from a holistic level. It should show the scope of it and if there is a relationship to any other documentation. Are you using Agile or Scrum? Show the methodology to your madness.

2: Scenarios

Reality check yourself before you wreck yourself. What are your use cases? Who is using your product? Describe as realistically as possible, with actual research backing if possible.

3: Overview of the Design

Cover any contextual information — explain any software interfaces, tech or applications used, processes, risks, and issues.

4: The Scope of the Job

Set this out at the very beginning of the project to prevent future issues. Define your design decisions and the functionality of the system. Help your users understand the characteristics, problems, and objectives of this product.

5: System Design

Explain your overall system architecture, interaction points, and data structures. This is your concept or system design with high-level solutions.

6: Design Details & Interface

This is where you get more into the nitty-gritty — system structure, components, interface, and modules. Describe the user interface explaining the screen images, objects and actions, and design rules. I like to keep my low-fidelity prototypes and mockups here.

7: Explanation of Testing Used

Explain how you test for functionality, usability, and performance so that all stakeholders can be confident that the product has been rigorously examined and checked for quality. I never really understood software product testing (nor the incredible importance of it) until I started working in QA at Hatch. This includes beta testing and production. We document our test cases and test results and how we go about that testing.

8: Deliverables

Timetables. Deadlines. Show us how you got it done. Show us the finished product and high fidelity mockups.

Photo by KOBU Agency on Unsplash

When to use

Documenting work this rigorously seems like a lot of work, especially when your company is sprinting fast. And you don’t have to document for small projects, but for the more comprehensive/complex issues, a well-laid-out doc can be incredibly helpful to have on hand. By collaborating often and letting everyone see these docs, our teams can use these as concise points of reference.

Product problems range greatly from the small to the hilariously convoluted. Documenting your process is not only a great way to organize the chaos, but also helps your peers keep up with the work and more effectively follow your process.