How to build a design documentation culture from scratch

The challenges and learnings you need to know before adopting a design documentation structure.


Thiago Vieira

3 years ago | 7 min read

Cover picture by Marten Bjork.

It is common for a design team, here and there, to miss project documentation when facing complex problems and a multidisciplinary team structure. If your team didn’t yet, this article will give you a chance to mitigate the chances of happening.

I wrote this based on mine and other designers’ experiences, as well as the need for project documentation in the Everon product department.

What issues designers usually face?

All good design processes start by understanding the problems we are expecting to solve, so I listed below common issues designers usually face during projects:

  1. Lack of knowledge sharing throughout designers and other team members, since design decisions are documented on stories and get mixed up with many other stories not related to each other, becoming difficult to track information, such as research outputs, journey maps, personas, etc.;
  2. Certain projects run with more than one team with different responsibilities, hence, frequently there are dependencies across-teams that are difficult to map and keep members aware of it, such as UI components that are not implemented yet, an API that needs to be changed or fully implemented before your team get hands dirty on it, etc.;
  3. Some decisions are unclear, and it is a mess to search for any kind of content through stories to justify those decisions, such as “why did we choose this component instead of that one?”, “why did we move forward with the flow this way?”, and many more;
  4. The consequence of these 3 bullets above is the lack of alignment with designers, developers and product team that entailed a too much back and forth of projects scenario to be changed in order to be feasible and move forward on implementation;

In a nutshell, the goal of project documentation is to improve points like these and bring more clarity on research, design awareness, and product alignment throughout the teams working with a certain complexity level on its structure.

Concerns taking into account

Might be easy to set a document structure in place just thinking about the problems listed above, but a few concerns need to be taken into account toward making it happen properly:

  1. It shouldn’t be disconnected from the process, otherwise, team members would need to use it besides the way they are already working;
  2. The bureaucracy level shouldn’t increase, otherwise, you would lose efficiency during projects;
  3. It shouldn’t be hard to use, otherwise, you wouldn’t get people on-board using the documentation structure;

How to start

Process mapping

It is important to look into the current process to understand your scenario, in order to change it and adapt the process, as mentioned by Dan Nessler on his articles How to apply a design thinking, HCD, UX or any creative process from scratch, to better fit the team expectations regarding each step outcome and its purpose.

Tweak the original recipe to your own needs and taste. - Dan Nassler

As mentioned on the evolved Double Diamond by Design Council, their process "clearly conveys a design process to designers and non-designers alike", with that in mind, the alignment during the process needs to exist not only with designers but with product owners and technical responsible too, what reminds me the product triad (desirability, feasibility, profitability) as explored by IDEO Design Thinking approach and said by Tim Brown:

Design thinking is a human-centered approach to innovation that draws from the designer’s toolkit to integrate the needs of people, the possibilities of technology, and the requirements for business success.

In order to create awareness of the impact of design Dave Cunningham’s explored How To Empower Design Teams By Measuring Value where he goes beyond the Double Diamond and mentions:

Design lives and breaths in different environments in different ways. In larger orgs projects, often balloon so get ditched or pivot. Stakeholders or key decision-makers can be out of reach. Business strategy can be unclear and not communicated well. Teams are fluid and can often be without the skills needed. All of these things are part of the ingredients which either prevent or allow design to thrive and grow.

So the process alignment needs to exist not only with designers but with product owners as well. To do so I encourage you to do research with other designers, from other companies and different contexts, to understand how they run their processes is enlightful.

After that, you can create a process that better fits your company’s needs, and in my experience, we’ve built it with the mix of the previous one and what would be the ideal process, based on the double diamond with extra steps to combine our context and good practices, such as:

Design process mapping.
Design process mapping.

1. Problem understanding:

  • Kickoff;
  • Journey Mapping;
  • Competitors analysis;
  • Stakeholders evaluation.

2. Problem definition:

  • Research synthesize;
  • Hypothesis and metrics.

3. Solution exploration:

  • Ideal Journey;
  • Brainstorming;
  • Filter feasible ideas;
  • Stakeholders validation.

4. Solution definition:

  • Prototype;
  • Validate 🔁 iterate;
  • Internal review (design critique).

5. DesignOps validation:

  • UX writing;
  • UI/Interaction;
  • Release communication.

6. Release:

  • Presentation to the engineering team and refinement;
  • Support development;
  • Follow metrics.

Is good to keep in mind that from the beginning of the process the PO and the Tech lead should be involved and have checkpoints in order to mitigate communication gaps and build team ownership in the project.

Process steps expectation

For a better understanding of what needs to be shared, it is crucial to map the outputs expected on each step and differs it from what is just a piece of information that will transit through the process.

Here I could come up with the expectations on each of those steps reflecting different clusters of information:

Design process mapping with steps outcome and clustering.
Design process mapping with steps outcome and clustering.

1. Briefing:

  • Project scope;
  • Discovery goal;
  • Problem framing (if there is one already);
  • List of stakeholders;
  • List of likely key users;
  • List of competitors;
  • Known risks.

2. Discovery:

  • Certainties, assumptions, and doubts;
  • Support tickets related to the project (if there is);
  • Users interviews;
  • Journey map;
  • Problem (re)framing;
  • Competitor analysis;
  • New risks;
  • Jobs to be done;
  • Hypothesis;
  • Discovery presentation.

3. Solution:

  • Ideal journey (opportunities mapping);
  • Evaluated sketches;
  • Usability test script;
  • Usability test results;
  • Refined prototype;

4. Metrics:

  • OKRs related to the project;
  • Successful metrics;
  • Unsuccessful metrics;
  • Period for analysis;
  • Possible dashboard views.

5. Design system:

  • Copy refinement;
  • UI refinement;
  • New components for documentation.

6. Launching:

  • Communication plan;
  • Team(s) presentation;
  • Assets for dev team;
  • Dashboard with metrics.

Structure draft

This is the moment the documentation structure starts to get shaped by grouping the pieces of information into topics according to their relation, based on the list of outcomes above.

Documentation structure drafts for Kickoff.
Documentation structure drafts for Kickoff.
Documentation structure drafts for Discovery.
Documentation structure drafts for Discovery.
Documentation structure drafts for Metrics.
Documentation structure drafts for Metrics.

For the sake of making it easy to use, it’s nice to add examples on how to fill in each document section, as placeholders and tools suggestion to be used when necessary.

Document section examples with instructions and examples.
Document section examples with instructions and examples.
Document section examples with instructions and examples.
Document section examples with instructions and examples.
Document section examples with instructions and examples.
Document section examples with instructions and examples.

Here are some examples of how to build your document with placeholders, I used the CAD Matrix introduced by Luis Alt where:

Everyone involved in the project is able to share with others everything they think about the scenario for which we will project and about the challenges in question.

For the problem framing, I used the How might we method as an example to turn problems into opportunities which you can explore broadly, as mentioned by IDEO:

This method suggests that a solution is possible and because they offer you the chance to answer them in a variety of ways.

The metrics document is where designers and product owners can define successful project metrics and goals, some examples are suggested by Zandre Coetzer on A framework to define your product metrics:

Internal Metrics: the metrics of your product (or experience), the things that tell you about how people are using what you designed; adoption, click-through rates, engagement.

After creating the first draft it’s only fair to validate and align with the users of this documentation. Designers and product owners may share their feedback over it and improvements may take place on the templates in order to get the document as close as possible to their needs and expectations. So in practice, this is how the documentation structure per project looks like in Everon’s stack:

Project X:

  1. Kickoff;
  2. Discovery;
  3. Release plan;
  4. Metrics;
  5. Launching;

Since Everon’s project management and documentation tools are based on Atlassian solutions (Jira and Confluence), this is where the documentation templates were available for our team's usage context, but below you can find the templates for download, so you can try it out yourself.

Outcome so far

By using this documentation structure in a couple of projects we could centralize and keep up to date project information and track of decisions, also we could inspire other departments on better documenting their process and projects, such as managers to embrace an initiative validation process, and the marketing team engaging on product releases communication, both connected to the product discovery, respectively in the beginning and at the end of the design process.


As any project related to processes, keep in mind this is just the very beginning. Improvements along the way are expected since the team will use more and more, so different needs might arise after getting feedback from the team, as experienced by Dave Nassler on How to rethink the Design process, fail, reflect and iterate:

The Revamped Double Diamond is a personal attempt at making sense of the various design processes, tools and methodologies out there.

While I'm trying the same however focused on documentation.

Some changes have been done already with the help of product owners and agile coaches, in a broader initiative base process rather than a project approach, and we hope to continuously do so in Everon.

Not every section of the documentation structure is mandatory, it will always depend on the project type and size to define what you’ll need to use.

Be mindful when using the templates I’ve shared because they might not fit your context like it fitted Everon’s setup, it is important to analyze your company’s needs.

The main point here is how to start looking into the outcome of design projects and get the best of design documentation as a powerful tool on your setup. This is quite related to the Metadesign mindset where Caio Vassão defines in this interview for lifework as:

Metadesign is the technique of creating methods, an approach to do so. It's not a method on its own but a different way of looking into a methodologic process.

Looking into what supports the project to rethink your process and how you document it will usually bring benefit, even more, if you work in a complex structure environment with many multifunctional teams that require an efficient knowledge sharing.

I trust that this article can inspire you and your team to build up your own design documentation culture and help on improving the way your team works and share with each other.


Created by

Thiago Vieira







Related Articles