Best Design Documentations

A design document (also known as software design document or technical specification), is a pre-written set of specifications that define how a website, application, or other software will work. It guides do not only developers but also designers, project managers and executives. Design documents are great for keeping all stake holders on the same page and allow smooth implementation with less risk of major changes. Let’s review in detail the different types of design documents you may use while doing your work!

For many product teams, design documentation is an afterthought. Instead, they follow the approach of, “We don’t have time to do it right now. Let’s focus on the design or development.” They postpone writing documentation until the very end of the product design process.

This can be a dangerous approach. A lack of thorough documentation causes confusion during the implementation phase of a design. Product teams are better off creating documentation throughout their workflow, essentially streamlining and empowering decision making. This will give everyone on the team a better understanding of each decision, every step of the way.

Let’s take a look at the concept of design documentation, explore why it’s an important investment of time, and go over some practical tips on how documenting design can be done properly.

What is design documentation?

Design documentation is a collection of documents and resources that covers all aspects of your product design. Documentation should include information about users, product features, and project deadlines; all essential implementation details; and design decisions that your team and stakeholders have agreed on.

Why invest in documentation design?

Clarify project requirements

Gaining stakeholder approval to begin implementing a design is one of the most important steps in the design process. You need to be on the same page with stakeholders to gain this approval. Proper documentation makes it easier to achieve this goal. How? Documentation helps you organize and deliver your thoughts to stakeholders, which in turn helps them understand how your design decisions will satisfy the user needs and their own business objectives.

Streamline design implementation

By documenting a design, you also aid in the implementation of it. Product design is a collaborative process, and in many cases, multiple people work on the project. It’s not always possible to share implementation details verbally (for example, when you work with remote teams). Thus, the design documents act as a single source of truth for everyone who is involved in product development and can rally your team around a specific goal.

Motivate your team

Good documentation tells a high-level story about the product and gets team members excited about the vision. It answers the questions, “How do we want to build this?” and, importantly, “Why do we want to build this?”

A list of essential docs

While documentation can vary from project to project, the following docs will be relevant to all. This information can be included in a single document or separated into multiple documents. Which approach you take will depend on the complexity of your project.

• Project overview – This document contains a high-level overview of the design and the goals the design team wants to accomplish. By reading this document, anyone should be able to understand the purpose of a project.
• Product requirements – This document covers the business and technical requirements of the design. It should be shared with stakeholders before starting the design to ensure that both types of requirements are satisfied. It’s also worth including in this doc information about constraints and assumptions because they will influence the design decisions.
• Project deliverables – This document provides information about the design artifacts established during the wireframing and prototyping phases (e.g., lo-fi wireframes, mock-ups, hi-fi prototypes) that will be provided as deliverables once implementation has been completed.
• Target audience information – This document lists relevant information about your audience, from user personas to data from user research. This information will help your team understand who your users are and what good design means to them (via their functional and aesthetic preferences). The doc serves as a reference for designers when sharing their rationale behind individual design decisions.
• User journeys – This document outlines the path a user may take to reach their goal when using a product.
• Design guidelines – This document describes the components and specifications required to build the solution.
• Style guides – This document lists a set of standards for the stylization of design. Styles, colors, and typefaces are essential pieces of this guide.
• Project scope and implementation plan – This document describes the roles and flow of cross-team collaboration. The implementation plan documents the requirements necessary to complete the implementation of the design. For simple projects, it might be a high-level overview of the steps required to complete the implementation. For complex projects, it can include a project timeline with information about the time required to complete each of the steps.
• Design validation and user testing – This document provides an overview of the practices to be executed during the product design cycle, as well as steps to be taken after product release to verify that the product satisfies user needs.
• Operational instructions – This document provides detailed instructions on how to perform common operational tasks after the design is implemented. For example, it can provide step-by-step instructions on how to roll out a new version of an app in the production environment.

Properly documenting design

Though there’s no single way to conduct design documentation, and it varies by product team, there are a few general recommendations that can benefit every project.

Make documentation usable for the target audience

It’s possible to identify three large groups of users for documentation: product team members, stakeholders, and end users. Every group has its own needs, and it’s important to consider this fact when working on your docs. Both the content of and the format for documentation should be adapted to suit your target audience.

Provide up-to-date documentation

Introduce a version control framework to keep your documentation up-to-date and therefore minimize the risk of incorrect design decisions. UX managers should validate the documentation at least once a month.

Work on design documentation incrementally

Documentation design isn’t a one-and-done activity. In many cases, it’s impossible to create all the docs in one attempt. Thus, product teams should work on documentation as they go through the project. Documentation should be a “living” project that is constantly updated as you work on the design. Product teams should invest time in creating a flexible, accessible structure—anyone from a team should be able to update documentation rather effortlessly.

Test documentation

Documentation is a by-product of your product design, and like other products, it should be tested with users. Ensure that users know how to use it and find the documentation valuable. You can also introduce a simple feedback loop, such as an online response form, so your users can record their reactions and help you continuously improve your documentation.

Avoid jargon

Every field has its own special language. When used in an appropriate context, this special language helps you communicate precisely with specialists that have the required expertise. But when you are uncertain about the expertise of your target audience, minimize the use of technical language in your documents.

The best documentation is the kind that your target audience can easily understand. It’s important to learn what’s appropriate for your audience and leave out jargon if it can be replaced by more familiar terms. Try reading the text out loud and evaluating it from the perspective of your documentation readers. Note any terms that might cause confusion and replace them with clearer terms.

Create easy access

Static paper-based documentation is quickly becoming a thing of the past. Modern documentation should be provided as an online resource. This format not only makes it easier for users to access the documentation, but it also simplifies the procedure for updates. Prioritize sections with information, and make sure search works fine. The structure you choose should follow the pattern that users follow when browsing the documentation.

Provide visual or code samples in the doc

It’s much easier to use information when you can match it with an actual design. To create contextual hierarchies and improve comprehension, documentation should include visual design and code snippets, not just plain words. Visual design or code samples make it easier for users to translate the information into design decisions.

Update documentation automatically

If some part of the design goes undocumented, it doesn’t exist. If elements of the design system go undocumented, you run the risk of duplicating elements. Try to keep documentation up-to-date with your product’s code by automating documentation. Rules and systems should be in place for documentation to be updated as soon as developers introduce a change in the front-end design. This includes both visual references and code samples.

Find patterns in existing docs and turn them into templates

Once you have created the documentation for a few projects, review the docs and try to identify common aspects of all the projects. Define templates for the standard parts to aid in the creation of design documentation. Templates will also serve as a foundation for building out design documents for your future projects.

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:

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:

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.

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.

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:

Why is UX documentation so important?

Even if you’re working as the only UX designer in an organization, it’s essential to maintain clear, accessible UX documentation. This will allow you to:

• Keep track of the past in order to inform the future. You won’t always remember what you did and why you did it, so thorough UX documentation will give you something to refer back to. This will help you make informed decisions for future design projects.
• Include others in the design process. UX and product design isn’t solely the domain of the designer(s). It impacts everyone working in the organisation, so it’s essential to allow others to understand how design decisions have been made—and how the product design process ties in with overarching business goals.

• Foster collaborative design. With designers, developers, and product owners all having a hand in the design process, UX documentation allows for a collaborative and transparent approach. It also serves as a single source of truth, making sure everybody is aligned and on the same page.
• Easily onboard new designers and hand over your work. UX documentation is a valuable company asset, ensuring that a product’s history is recorded and not lost over time (or with the departure of a team member). If you ever need to bring new people into a project or hand it over, your UX documentation will make the task significantly easier.

Conclusion

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

When software and systems engineers develop their pieces of code, they design the software with a thorough documentation and design documentation. A typical documentation that is created during implementation are requirement documents/specifications, high-level design documentation, interface designs, object models, data flow diagrams (DFD), function point analyses (FPA), test cases and production details.