Post Image

The 3-Step Guide to Lightweight UX Documentation

Yona Gidalevitz
By Yona Gidalevitz on 20th June, 2016 Updated on 24th September, 2020


The life of a UX specialist becomes hectic in the blink of an eye.

Between research, design, client interaction, team collaboration, there may not be much time left in the day to create documentation strategically.

Even so, can time spent perfecting documentation really be considered a waste? Yes, and no. It depends on the purpose, and usefulness, of the documentation.

Generalized documentation, created for no other purpose than to leave a paper trail, for example, is too general to be useful, and (effectively) purposeless. Highly focused documentation, on the other hand, can be both useful and purposeful.

In order to ensure that the documentation you create isn’t taking away from time that could be spent on design and research, consider the following questions:

  1. Is the UX documentation going to drive decision making?
  2. Is your UX documentation usable to your team?

Based on my experience at Codal, this article aims to help UX specialists and their teams answer these difficult questions.

1. Give your UX documentation purpose by determining it how drives decision making.

Fact: UX documentation has purpose if it drive decisions.

Think about it: UX documentation has a wide variety of end users—including designers, developers, QA specialists, stakeholders, and management—all of whom may (or may not) use a particular document to make informed decisions during the course of their work.

In fact, any given document has the capacity to impact decisions.

Let’s consider the Agile software development lifecycle (SDLC), for a moment. One particular document may impact one particular activity in the SDLC, while a different document may affect a number of subsequent activities.

For this reason, it’s extremely important to take into consideration the lifecycle of the document. The lifecycle of a document refers to the path that it will take, from user to user, before it is no longer needed.

It’s a matter of ROI.

In general—and there are exceptions—the longer a document remains relevant during the SDLC, the greater the return on time spent perfecting it. This is because these documents drive decision making across multiple stages.

In other words, UX specialists need only make documentation where it is really needed. Otherwise, you’re wasting of time and money.

You may be wondering, but how do I determine the lifecycle of a document before I’ve even made it?

Determining the lifecycle of a document is as simple as looking at it’s various use cases.

Take, for instance, the following empathy map we created at Codal for a client.



Above: an empathy map created by Codal

UX specialists know that UX research documents tend to make great decision-making tools.

Let’s investigate the lifecycle of the above empathy map. To do so, we need to consider who will likely use the document, and for what? In this case, the document in question is a compilation of user research results.

User research results drives the entire product strategy during the SDLC. Even if developers and PMs don’t own the document, its insights will inevitably influence their work.

If we follow the logic presented earlier, then an empathy map is an incredible investment in the future of the product. Consider that a document that’s always worth creating (the earlier, the better).

2. Make your UX documentation useful by meeting the requirements of the target audience.

Fact: a document can drive decision-making, yet still be useless at the same time.

Think about it: Developers don’t always have equal say in how to lay out a particular page—they might just follow the designs created by the UX & UI designers. Thus, the design documentation, however poor it may be, will drive development decisions.

In other words, “driving decisions” is one concept, and “driving good decisions” is something else altogether.

Keeping in mind that documentation has not only a purpose, but also a target audience, is likely to help stimulate good decision-making among targeted users.

The converse is also true.

Documentation that doesn’t consider the audience’s specific requirements is liable to miscommunicate the intentions of the UX specialist.

Avoiding the pitfalls of non-targeted documentation is simple:

  • Deduce the target user-base.
  • Analyze how the document will be used.
  • Craft the document so that it speaks the language of the user.

Consider the following interactive wireframe.


Above: an interactive wireframe created for a Codal client

One can determine the target users of any document by examining its purpose.

Static wireframes are typically used as visual scaffolds so that the interface designer may craft a pixel-perfect mockup of the UX designer’s vision.

Interactive wireframes, however, can also be used by developers to gauge dependencies and interaction models. Product managers can also quickly assess the feature breadth (horizontal requirements) and depth (vertical requirements). QA specialists may even use the interactive wireframe to double-check the work of the developer in re-creating the functionality.

As such, we can deduce that the target audience for an interactive wireframe includes:

  • UI designers
  • Product managers
  • Web / mobile developers
  • QA Specialists

In order to ensure that the document is useful, it must cater to the specific needs of each of the aforementioned users. Otherwise, our document is effectively useless.

As LookThink shows in the below annotated prototype created in UXPin, here’s how you can quickly tailor the document to each audience:

  • To help UI designers – Estimate image and layout dimensions.
  • To help product managers – Note any “wobbler” features that may provide additional value, but exceed current scope.
  • To help developers – Add notes to clarify complex functionality and ask for input on feasibility.
  • To help QA specialists – Note which functionality is up for discussion, and which the team accepts.


Above: Annotated prototype created by LookThink for a healthcare platform.

3. Improve documentation usability by keeping it focused.

Fact: documentation, like software, depends heavily on usability.

Think about it: no matter how much good content you include in your documentation, it’s for nothing if the reader struggles to understand it. We can distill document usability down to one word: focus.

Often, UX specialists have so much to say about their work that it gets in the way of the data that must be communicated. This can be the source of many problems, especially when the data gets lost in translation.

Human beings don’t like to read extraneous details. How many times in your life have you been thrilled to read a 20-30 page document? You need to keep it focused.

Take, for instance, the following sitemap, created for one of Codal’s client projects.


Above: a sitemap created for a Codal client.

This is a focused document.

Note that there are no extraneous details, no excessive notes, and everything is confined to one page. The target audience is able to consume the intended data, nothing more, nothing less.

Achieving focus in UX documentation is simply a matter of applying the core principles of purpose and usefulness, as discussed previously. The above document illustrates this point quite effectively.

Here’s the truth: UI designers and developers might not need to hear all the reasoning behind the choices that you’ve made. Either save it for an in-person discussion, or only highlight the top 3-5 decisions.

There are exceptions, of course. If the document is intended for a member of the QA team, you might need to explain all your reasoning so that they can adequately test the functionality of the software—and even then, it’s not always needed.

Documentation isn’t a paper trail.

UX Specialists: respect your own time, and that of your coworkers. Don’t waste time crafting documentation that isn’t focused. Remember to keep it useful and purposeful—remove  extraneous details.

Know your audience, and their needs. It’ll go a long way in determining exactly which details are extraneous, and which are not. Ensure that the documentation you create will be used to drive decision making, otherwise you are simply wasting your time.

And here’s a final tip: create a documentation hub that links out to all relevant documents.

As Autodesk shows below in UXPin, aside from everything being in one place, you can include explanatory notes in the hub, rather than clutter the actual decision-making documents.


Join the world's best designers who use UXPin.

Sign up for a free trial.
Still hungry for the design?

UXPin is a product design platform used by the best designers on the planet. Let your team easily design, collaborate, and present from low-fidelity wireframes to fully-interactive prototypes.

Start your free trial

These e-Books might interest you