Now recruiting for a Senior UX Design Freelancer! Click here for more information →
Foundational UX

UX Design Documentation Guide

August 1, 2023
Written By:
No items found.

As a UX designer, you’ve probably done plenty of specs and redlining, but you might not have written much structured documentation about your design decisions and process.

While it might seem like snooze-worthy work you don’t have time for, prioritizing the practice of writing stuff down is well worth the effort. By documenting your work, you’ll bring order to the software development chaos, feel awesome about what you’ve accomplished, and collaborate better with the whole team. Design documentation is especially crucial when you’re working on complex feature sets for enterprise UX workflows, with many stakeholders and users involved.

If you’re not sure where to begin when it comes to design documentation, look no further: in this article, we’re serving hot tips on how to document your stuff and be more successful in your design work.

What is design documentation?

Let’s kick things off with a definition: Design documentation is a set of documents and resources that record the unique process involved in creating, working on, measuring, and iterating a new feature.

With design documentation, you aren’t just writing documents about something you know or about what should be done. Rather, you’re logging what you’ve actually done and why you did it.  

You can document things like:

  • Interaction & behaviour
  • Logic and technical considerations
  • User flow and other overview docs
  • Individual screens and visual specifications (redlining)
  • Design logic and rationale
  • Design principles
  • Product strategy
  • User data and evidence

Why bother with design documentation?

Documentation isn’t just for devs

Product design documentation isn’t just for devs: it’s for YOU. It allows you to reflect on your design choices and log your thoughts for later (your future self will thank you 🔮).

But you don’t work in a bubble—UX design impacts everyone in the organization, and documenting your work benefits other teams involved in the process, like product and marketing.

Let’s say you document your design principles (more on that later), explaining why they exist and how they’ll be acted out. The VP of product can use those principles to write a blog post alluding to what’s coming up, and the marketing team can use them to brainstorm taglines for the next product. #teamworkmakesthedreamwork.

Documentation is where product & strategy come together

Design documentation represents how you’re manifesting and acting out the product strategy. It explains how your design supports the higher level intention of the product and who you’re building the product for. You know, the important stuff.

What’s more, documentation acts as a source of truth, getting everyone on the same page with product strategy and design decisions.

Documenting helps you sanity check yourself

Documenting your thought process while designing is like telling your design story—and it helps you find your plot holes. Did you cover everything in this project? Are there any missing pieces? Why did you make certain choices? How did you get to where you are now?

By writing things down, you avoid missing any crucial details, big and small. It’s like QAing your own work.

Design documentation tools

There are plenty of different platforms you can use for design documentation, like Confluence, Notion, and Figma, to name a few. Whichever tool you pick, it’s good to have a legit place for textual documentation. Your floating post-its in Figma, for example, can easily be moved and deleted by someone else.

Together with your team, figure out the best way to organize your shared workspaces so that everyone has access to the documentation, but no one can accidentally change or delete important notes.

Figma Tips
Get the most out of Figma by using these wonderfully useful features:
  • Sections: Separate your canvas into smaller sections based on related ideas or development stages, like “in-scope” and “other stuff for later,” making it easy for collaborators to navigate.
  • Status: Label sections as “Ready for development.” If devs use the “Dev Mode” view, they’ll only see what’s relevant for them and you’ll avoid any mix-ups.
🔥Hot take: Lots of people don’t use Figma’s prototype mode because they’re used to seeing static mockups. So don’t force anyone into clickable prototypes—your documentation should compensate for people’s behaviour. Otherwise, interactive elements and hover states might get missed.

Alternatively, you can also create fake buttons that say “Click here to play the prototype” so it’s easy for others to find. Remember to keep your documentation user-friendly and intuitive—treat your audience like users.

Product design documentation checklist

There’s no perfect formula for design documentation—your approach will be unique to your team and culture. But here’s the key stuff you need to include regardless of how you structure your docs.

The product strategy context

When designing a brand new feature set, be super clear about why you’re building it, what audience you’re targeting, and where the feature plugs in. In other words, outline the product strategy context.

This info often comes from the design brief, which covers the goals and intention of what you’re trying to achieve. In your documentation, show how these higher level goals sprinkle into your design methods and mechanisms—the “how” of the product strategy.

This document intended to give the overall team a sense of the feature epics and what they involved. We included the goal and assumptions.

Patterns and design systems

Find yourself re-communicating the same quick fixes and solutions to your dev team over and over again? That’s something you should document in your design system as a high-level rule.

For example, you might stumble upon the perfect breakpoint logic while working on a specific page during a sprint. When you consistently apply that same structure to other pages with breakpoint problems, that becomes a pattern worth documenting and communicating to the team.

Be sure to differentiate the decisions that are local vs. global, since some things will apply to specific pages or features for a super specific user subset. As you continue to work with the product, the global things will become clear.

Your design rationale

While a spec document outlines the “what” of UX design, your design rationale explains why you did what you did. Documenting your design rationale involves logging all key decisions relating to the product or feature you’re working on.

Your design rationale is likely in a constant state of flux as you build, so it’s easy to forget your thinking process along the way. That’s why meticulously logging your design decisions is essential. Of course, you don’t need to log your every thought, but include the key decisions that show how you arrived at the final deliverable.

Point out any cases where there are unknowns with your rationale, and clarify your confidence level. You can say, for instance, “We haven’t figured this out yet, but we’re building this so we can test whether it works.”

🧓☝️However, if you can’t explain why you did something, especially when it’s consequential, that’s a red flag. As designers, we need to think both abstractly and concretely, using our imagination and multiple data points when coming up with new ideas. Understanding your thinking process is a key part of your practice that you can’t ignore.

The upside is that being able to recognize your real-time thinking helps you articulate it better and uncover any holes and problems in your reasoning. Half of our job is being wrong, so get hip to that 😉

Design principles

Closely related to your design rationale, design principles are guidelines that help your team stay aligned as you build products or features. They help you make design decisions that prioritize the project objectives. For example, one design principle might be to make information readily available, and you act that out by sharing sophisticated tool tips and creating a design convention of using tooltips to define jargon and acronyms.  

Documenting your design principles makes them official. Once you’ve written down these foundational pillars, you can move onto documenting the nitty-gritty stuff.

Capture different versions

Leave yourself a papertrail that reflects your thoughts for future versions—especially when designing bigger feature sets. Capture your design decisions early on so that you can refer to them when you’re working on the next versions of your product. It’s so much easier to come back to a feature set when you have a clear sense of what you were doing and what the next steps were.

Documenting your thoughts for future versions also ensures continuity with the experience users have gotten used to. You might do versioning on the fly, so just make sure devs don’t see future stuff and think it’s in scope.

Don’t forget about edge cases

We’ve talked about including high-level stuff in your design documentation (which are surprisingly easy to forget), but you also want to cover the edge cases. What are the wacky and weird situations that might arise? 🤪

Ask yourself: would you rather find an edge case when you’re still making mockups, or when the due date is tomorrow and you’re pushing to production? If you don’t give yourself time for this early on, it’ll be most costly and time-intensive to fix later.

Save yourself the crises and document the edge cases for layouts and super interactive stuff. Involve QA in this process—they’re really good at finding edge cases and breaking stuff. 🕵️

Tips for design documentation

Next, let’s walk through some tips for how to go about documenting your design decisions.

Get your head in the game

If you haven’t already integrated documentation into your workflow, it’s time to shift your mental model and make it a key part of your role as a designer. Be disciplined, and take a slow and steady approach when documenting your design.

Ease yourself into the process by starting with some simple steps. For instance, the next time you create wireframes, jot down explanations for each design choice on sticky notes.

Throughout your workweek, be mindful of moments when you realize how easy it would be to forget crucial discussions, conclusions, or ideas. How often does it happen? By making documentation a habit, you’ll gradually get used to the process and it’ll soon feel like second nature to you.


Bring the crew together

Have a session with your team to go through what everyone expects to see in design documentation. Approach it from different angles, and ask the crew:

  • What do you think should be in the documentation?
  • What is the dev team used to seeing?
  • What has often been missing from documentation?
  • What is the product team able to provide (in terms of strategic documentation)?
  • What’s doable to produce (so that documenting can be easily integrated into your typical workflow)?

Chances are, the team already has ways of documenting things—you’re not starting from complete scratch, but you’re exchanging information and ideas about how to improve documentation.

After this session, decide on a realistic middle ground for documentation that works for everyone. Avoid time-consuming documentation practices like extracting screenshots from your design tool into yet another place that you’ll need to keep manually updating.

Create a documentation template that designers can use whenever they start something new. This way, your documentation is sure to be useful and consistent, and you don’t need to reinvent the wheel every time.

Don’t forget to involve QA here too—they need to know the ins and outs of the design even if they don’t attend all the feature kick offs and estimation meetings.

Go from overview to more specific

If you jump straight into the granular stuff in your design documentation, you leave a lot of gaps for people to fill in themselves. First, take a step back to show the bigger picture and the navigational context, i.e. where you came from and how you got there.

Introduce new features with a low-fidelity flowchart—everyone loves a good flowchart 😍 They get people warmed up and show how the new thing you’re building fits within the existing user flow. Since mockups and prototypes often start right in the meat of things, it’s all too easy to create something new and forget to give it a home. To avoid your new features and workflows from getting lost in the abyss, communicate where it plugs in (like a menu or submenu), why it makes the most sense there, and how users can reach it (the entry point).

This is an example of design rationale which has a flowchart overview to help ease understanding.

We worked on this flowchart to share with the dev team how we were expecting search results to work, and the different destinations users could reach depending on the type of query they ran.

Use a matrix for conditional logic

Use a matrix for interaction documentation with conditional logic. This is especially useful when you have many states. For example, if you are part of a community, then you’ll see this type of phrase. If you share the link with one person, then you’ll see this message. If you share it with two people, then you’ll see this other message, and so on. In your matrix, be explicit about what’s a new feature and what’s a redesigned feature.

We used this matrix to better visualize how our different data types related to each other. Notice how colour-coding can be pretty and useful!

It’s much easier and efficient to represent all the variables in a matrix instead than of writing them out in a long-form text. You don’t want to have people deduce anything—QA will be logging in to your prototype with different user settings, and they need to refer to one source of truth.

Explain how the documentation works

Get meta and document the documentation. 🤓As a UX designer, you’re used to the tools you use every day, but not everyone knows all the features inside out. To make your documentation inclusive and transparent, tell people how to use the software and where to to find what. For example, say “If you’re looking for the main component, use this button—it’ll bring you to the right place in the design system.”

You might want to name one mega document your “design document,” and have conventions and nomenclature for your file structure. Are there any special words you’re using? Create a glossary for all those specific terms, as well as for the abbreviations you use (so no one’s left wondering WTF is a KWHL?!)

Using Confluence, we stuck to a standard format to document the interactions in new features. One column for visual reference, and another for more details around behaviour.

Make your documentation appropriate for your audience. Sometimes it’s just devs and product people, and sometimes it’s the whole company. You can create a landing page in the prototype so that wherever people start, they’ll land on a table of contents that shows how to use the prototype.

Don’t like writing? Use Loom 🎥
Some people learn best by reading, while others are more visual learners. Either way, it can be overwhelming to read design documentation—there might be 10 screens that all look the same, and people have no idea where to start.

Loom is a useful tool for orienting people through your documentation like a READ ME. You can create a Loom video for each part of a workflow, and explain the user behaviour with your voice. People can refer back to these videos when they need to, and leave comments if anything is unclear.

In a nutshell

Design documentation requires a fine balance of time and effort. You don’t need to create super fancy web pages with embedded prototypes—documentation should be easy to produce—but you do need to put some elbow grease into it.

If you find yourself saying “We don’t have time to document anything, ever,” that’s a problem. It’s like saying “We don’t have time to think things through at any level, ever.” If you don’t make time for documenting your design rationale or process as you go through versioning, you’ll lose all that effort you put in. And we bet you’re a smart cookie and had some good thinking along the way!

Design documentation ensures you never have to start from a blank page again. The beauty of knowledge work is that you can pick up from the last person or from your past self. When you share knowledge with the organization, you gain clarity, save hours on design work, make well-informed decisions, and work better as a team.

Be a better designer
Our fun, informative and funny newsletter will help you make better design decisions. Plus you get to hear about hot off the press content.

Want 1:1 help? Our crew does UX mentoring for product teams. Feel free to reach out.

UX Heuristic Report Template Kit

Spend your time and life force on capturing heuristics problems rather than endless visual fiddling. Meganne Ohata will guide you the whole way, so you can propel your work and become their most trusted advisor.

$79
$59
Learn more
ux heuristics series

Download our Table UX Audit Checklist

Do a mini UX audit on your table views & find your trouble spots with this free guide.

Available in a printable version (pdf), plain text markdown, Apple Keynote or Microsoft Powerpoint.

Please fill in the form below and it will be in your inbox shortly after.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
letters

Want to dig deeper on flow diagrams?

Be the first to know about our upcoming release!

If you found this intro content useful and find yourself needing to express yourself more efficiently on your software team, this training is for you. Our new flowchart training includes real-life enterprise stories and examples for using flowcharts for UX. You’ll get tips on how to make your diagramming efforts successful, how to derive info for the flow charts, and how to get others to use and participate in the diagramming process.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Get to know us
“Your article made me realize our tables suck.”
Matthew S.
Mazumago
Previous Post
Search UX Best Practices
Next Post
Dashboard Design UX Patterns