How to create great UX documents

10 minutes read

Like it or not the UX profession is very much in the documents game. From personas to wireframes and from user journeys to sitemaps, UX is knee deep in documentation. Even with the Agile UX drive to keep documentation to a minimum (which I whole heartedly agree with), in the same way that a football team can’t score goals without a bit of passing (unless you have Maradona on your team); a design team can’t create great designs without a bit of documentation. Sure it’s scoring goals that everyone is working towards but the passing is a necessary step on the way (even if it often gets forgotten about).

Not only is the UX profession in the documents game but as a UX professional you’re invariably judged by not only the quality of your work (whether it’s a design, piece of research, strategy or evaluation), but also by the quality of your documentation. Great UX work is going to be hidden by poor documentation so it’s imperative that any UX documents you and your team produce are up to scratch. But what makes a great UX document and how do you ensure that your documents achieve what you need them to?

What is a UX document?

Before I start talking about how to create great UX documents I’m going to get all philosophical (bear with me) and briefly talk about where a UX document starts and where it ends. As Jared Spool outlines in his excellent Design’s Fully-Baked Deliverables and Half-Baked Artifacts article, everything that a UX professional or UX team produces shouldn’t automatically be considered as a UX document (even if it might look like one). Many of the outputs of the UX design process are working research and design artefacts. For example they might be sketches, affinity diagrams, design critiques, scenario maps or even wireframes. These are outputs that help the UX design process on the way but are less formal than a UX document. They are not really meant to stand on their own as deliverables and typically capture something that is still very much in a high state of flux. A UX document on the other hand is typically more concrete and often communicates the decisions that have been made, whether it’s the design to pursue or the users to target. Whilst it’s of course a good idea to make great design and research artefacts, I don’t want you to think that everything that a UX team and UX professional creates is always a UX document (my little disclaimer if you will).

What makes a great UX document?

Hmm… what makes a great UX document? Beauty? Simplicity? Elegance? Well possibly but a great UX document is not just about looking good (indeed this isn’t always strictly necessary). To paraphrase the legendary Steve Jobs, to be described as ‘insanely great’ a UX document has to be:

1. Useful – First and foremost a great UX document is useful to its audience. It clearly contributes to the overall goal of the work being undertaken– whether that’s to create a design, define a strategy or carry out some research.
2. Appropriate – A great UX document is appropriate to its purpose, to the situation and to its audience. For example, an internal team document doesn’t need to look like a work of art. Equally a document that’s going to be widely circulated shouldn’t look like it’s been cobbled together in 5 mins.
3. Usable – Just like a usable interface, a great UX document is easy to understand and use. Ideally it should be as self-explanatory as possible.
4. Presentable – A great UX document doesn’t need to be a work of art, but it should be presentable (appropriately presentable if you will).
5. Accessible – A great UX document should be easily accessible. It should be easy to find, easy to access and in a suitable file format.

Planning your UX documents

As the old saying goes, fail to plan, plan to fail. The first step to creating a great UX document is to plan out the document. In the past I’ve found it useful to consider the following 5 Ws and 1 lonely H, namely:

• Why? – Why is the document being created in the first place?
• Who? – Who is the document for?
• What? – What is the purpose of the document?
• When? – When is the document needed?
• Where? – Where will the document be used in the UX design process?
• How? – How will the document be used?

Having asked yourself and any fellow document authors these questions you’re also in a good place to think about whether you actually need to create a UX document in the first place. To put it simply, is the benefit that the document can bring worth the effort? We all know that writing a document can be a painful, painful, painful process (did I mention it could be painful). Well, will the pain be worth the potential gain? It might be that rather than writing a lengthy document you could instead put together a presentation, arrange a show and tell or create a prototype.

Choosing your UX document type

Having established that yes, on reflection you do need a UX document you have to decide what sort of document (or documents) is going to serve you best? As I’ve previously mentioned UX is awash with documents so you have a lot of different types to choose from. Once again go back to those planning questions and think about what sort of document is most appropriate. For example, you might choose to use a customer experience map or storyboard to show the customer’s user journey, or alternatively a simple narrative based scenario. Also don’t be afraid to use a combination of documents. After all, you don’t want to try to shoehorn everything into one almighty UX document. Often you will want a number of different documents for different audiences and purposes, such as a summary document for senior business stakeholders (who are far too busy to read trivial UX documents) and a more detailed document for the design and development team.

Getting inspiration

Rather than re-inventing the wheel each time you create a new UX document (assuming this is the first time you’ve created this sort of document) it’s much easier to first grab some examples and use them as inspiration. Notice I said ‘inspiration’. Don’t just blindly copy an example you’ve found but instead evaluate what you like and don’t like about the document. Perhaps even stick it in front of some of your potential document users to see what they think (more of this later). There is no set in stone format for any UX document; it’s quite rightly a free for all because every project, every organisation, every team and every document is different.

A Google image search is a great way to quickly build up a collection of example documents. It’s also a good idea to maintain a repository of good UX documents within your team or organisation (in the past I’ve used Basecamp for this). This can be a really useful resource because if someone needs to create a new UX document, they can quickly grab some examples, potentially even templates to use with minimal effort.

Making your UX documents useful

So you’ve decided on your document type and then grabbed a bunch of example documents. Great, but how do you ensure that your UX document is ultimately useful to its audience? Simple, apply a bit of user-centred design thinking!

Consider who your audience is, what their domain knowledge is and ultimately how they are likely to be using the document. What are their needs and requirements? Is the document also going to be used by people you’ve perhaps not even considered (such as technical authors)? Why not go out and ask your audience? What will be most useful to them? You could even create some quick sketch personas for your audience or some empathy maps. If you tackle a UX document in the same way that you would take a UX design problem then it should hopefully become apparent exactly what will make your UX document  truly useful.

Making your UX documents appropriate

A UX document should be appropriate to its purpose, to the situation and to its audience. It’s quite possible to have a document that is very useful, but not wholly appropriate. For example, a document that’s going to be seen by very senior business stakeholders but that is very rough around the edges might be deemed inappropriate. It might be appropriate for use within the team, but not to a wider audience, especially as the document is ultimately reflecting the work of the team. Equally a document that is primarily going to be used within the team but that is overly polished (looking like something produced by an uber digital agency) is not really appropriate. Not only should the document itself be appropriate, but the amount of time and effort spent on the document should also be appropriate (the two really go hand in hand).

Determining what is and what is not appropriate ultimately comes down to the goals of the document and who the audience is likely to be. What is appropriate for one audience might not be to another. Think about what sort of documents the intended audience are used to seeing and what the goals of the document are. Is it just about communicating a design, or is it also about making the yourself or the team look good (don’t be shy about that)? Is it a key deliverable or just a minor stepping stone in the design process?

Making your UX documents usable

The ISO defines usability as, “The extent to which a product can be used by specified users to achieve specified goals with effectiveness, efficiency, and satisfaction in a specified context of use”. Now replace the word ‘product’ with the word ‘document’ and you have a pretty good definition of a usable document. Not only should the document be effective, efficient and satisfying to use, it should also be user friendly. Ideally it should be as self-explanatory as possible. Someone shouldn’t need to be subjected to a 5 minute lecture before being able to understand the document, or have to hunt around for other documents to piece together what the hell is going on.

Making a document usable is much like making a design usable. It’s all about following good design principles and practices. For examples, having text that is big enough to read easily, providing a table of contents, providing keys, showing page numbers and including help where necessary. Treat your documents as a mini-design project and administer the same tender loving care and attention on your UX documents as (hopefully) you do on your digital design work.

Making your UX documents presentable

As I said previously a UX document is not a work of art (unless it is, er what is art anyway?), but equally it should be presentable. The level of presentation should of course be appropriate to the situation and audience (see making your UX documents appropriate above), but really there are no excuses for creating sloppy UX documents with typos, inconsistencies and visuals that make your eyes bleed.

In terms of making your UX documents presentable, once again simply apply good design principles. Use consistent fonts, good line spacing and colours that complement one another. Utilise spacing, balance and grouping to create a beautiful, elegant document. If like myself you have minimal graphic design skills then don’t be afraid to ask a friendly graphic designer for help. The offer of a Quad Grande, non fat, extra hot caramel, macchiato upside down coffee is sure to coax them out of their graphic design lair to assist you (not that I’m likening graphic designers to caffeine obsessed badgers you understand).

You might also want to think about establishing a visual house style for your UX documents in order to maintain some visual consistency between them. Indeed, there might already be a house style that you will need to adhere to. After all, you don’t want to fall foul of the much feared in-house branding police!

Making your UX documents accessible

You can have the best UX documents in the world but they’re utterly useless (like Wayne Rooney on the left wing) unless they can be easily found and accessed by those that need to use them. Digital documents are generally better than printed and rather than emailing out documents try to have a central document repository (such as an online fileshare or extranet) you can point people towards. This not only keeps all the documents together and provides one place for people to go to, it also makes it easier to ensure that people are always looking at the most up-to-date version of a document. Finally don’t forget to use a file format that:

1. People can access on their device of choice (which could be a laptop, mobile or tablet)
2. Doesn’t lead to massive bloated files

You can rarely go wrong with good old PDF, or heaven forbid even Microsoft Office formats.

Good housekeeping

Like tidying up your room at the end of the day and scrubbing those annoying watermarks that appear when people don’t use a coaster (you know who you are), you also shouldn’t neglect your UX documentation good housekeeping. Remember to include details such as the document version number, author, date, change history and details of any related documents. A document overview can also sometimes be useful outlining who the document is for and what the purpose of the document is.

Evaluating your UX documents

Like all good usability professionals I’m sure that you’ve previously carried out usability testing on a design, or perhaps watched usability testing sessions taking place. But have you ever usability tested a document? Why not? In the same way that usability testing will give an indication of how usable and appropriate a design is, it can also do the same for a document.

Try to test a document as early as possible so that feedback can be used to iterate the document. You could ask people to describe what they think the document is communicating; how they would use the document and whether anything is unclear to them? It’s also a good idea to ask for feedback once a document has been distributed. Perhaps send out a quick feedback survey or speak to a few people that have used the document in anger (hopefully not anger that has been induced by the document). Even if it’s too late to change that document you can often find things out that will make the next document like it truly ‘insanely great’.

More about UX documents

• 50 Free UI and Web Design Wireframing Kits, Resources and Source Files (Smashing Magazine)
• Communicating Design: Developing Web Site Documentation for Design and Planning (Dan Brown)
• Design’s Fully-Baked Deliverables and Half-Baked Artifacts (User Interface Engineering)