10 Principles for Good UX Design Documentation

This is a Manifesto for UX Design Deliverables.

During my time at Canonical I was working on the Ubuntu mobile and desktop Software Development Kit (SDK) in a genuinely, open-sourced fashion. Team members were distributed across different business initiatives and remotely located all over the world. Some were full-time employees and others just felt passionate about the idea of open source software and voluntarily chipped in thousands of hours of dedicated work. We were using existing tools for online collaboration and occasionally built our own channels to sync up more effectively. Larger and smaller offsite events throughout the year brought together the community of roughly 600 developers to govern and steer the next version of Ubuntu powered digital services.

Ubuntu runs Netflix cloud servers, supports Uber, Tesla, Google, governments and even the international space station. Ubuntu instances have been installed 20 million times in 2015. (Source)

In such spirit, Canonical has managed to thrive and scale with an open source software development strategy from the ground up since 2004, when it was first founded. Being part of this unique organizational set-up and having experienced ways of creating software that has a truly global impact, lead me to rethink and redesign my UX design documentation.

Today, I am uncovering better ways of developing important UX design and research documentation for distributed teams. These can include customer profile kits, service- and experience maps, transformation maps, affinity cards, user journeys, wire-flows, jobs-to-be-done live dashboards, behavioural diaries, interview discussion guides, user research reports, motion-gifs, design release notes, UX compass metrics, just to name a few. Here are ten principles everyone can adopt:

1. Good UX design documentation is always up to date.

When setting up your UX reporting and feedback tools think more in feeds and streams, less in ‘static documents’ that might never change once delivered. Version control these streams and keep them easy to edit for everybody, without the need to go through long how-to tutorials, on-boarding processes or tooling registration hoops. Allow people to follow the continuous progress and receive updates and notifications on channels they can choose. Remember; a ‘document’ that does not need updating on a regular basis is not worth creating and will quickly loose it’s relevancy for the business and products. Treat UX as a continuous engagement with team-members (contributors), the business, the product and it’s end-users.

“UX is the controlled continuous curation of multiple interactions within a given system or environment — this includes interactions with your colleagues.”

2. Good UX design documentation is co-created, peer-reviewed and segmented.

Building on the first principle, make sure you use common, open and accessible tools that allow co-creation and contribution over the internet via well established apps, proven browsers and secure web technologies. Establish an easy to follow contribution process that can be quickly understood and replicated by a large audience of diverse people coming from brand and marketing departments, tech, analytics, customer service, sales, business intelligence and even from people at the executive level. Occasionally, it makes sense to open up your design documentation to end users and allow for real-time contribution. Produce shared conclusions not solo assessments.

3. Good UX design documentation is open.

Keep your UX streams and reporting feeds broadly visible and accessible. Encourage team members to distribute findings widely through internal and external sharing tools. Make the content snippets you produce easy to discover and searchable at any time, from anywhere. If your company feels inclined to lock important documents and data streams behind a security wall, then make sure access can be granted easily through multiple, verified gatekeepers.

4. Good UX design documentation is data informed.

At the start of a new project or initiative you find yourself working with a lot of assumptions, speculative data, outdated research and biased opinions, which is totally fine. As you go along, however, replace these hypotheses with real data and insights. Ear-mark elements that have not been validated yet, so readers and contributors know were there are gaps and how they can help filling them. While your behavioural data should have an answer to the WHAT and WHY, it usually also falls into three superordinate categories, so make sure you have something in each bucket for: Market insights (implications of competition and market, behavioural economics), customer insights (most relevant needs of target groups and behaviours) and product insights (most relevant product benefits).

5. Good UX design documentation has many actionable steps.

Collecting relevant requirements and data is a hard task, but translating those insights into tangible and achievable tasks is even harder. What’s even more of a challenge is passing on some of the tasks to distributed teams and individuals who have specific ways of dealing with incoming requests and demanding tasks.

“Say goodbye to the official ‘deliverables handover day’ between designer and developer and embrace continuous (UX) support of your colleagues.”

At Canonical I learned that thinking of actionable steps (quick wins and long shots that are actionable, accessible and audible) for specific audiences from the beginning of a new design or research initiative is key to success. You will see your work implemented into the final product and service much faster when you not only keep the end users constantly in mind, but also the people you work with. Say goodbye to the official ‘deliverables handover day’ between researcher, designer and developer and embrace continuous (UX) support – aka development – of your colleagues.

6. Good UX design documentation is tight to compass metrics.

What’s a compass metric? Well, think of something that will help your ‘document’, project, product, service, customer or even team member (contributor) succeed. A compass metric is not something written in stone and shifts as you and your venture are cruising along the learning and (design) iteration infinite loop. What’s important though is that you define it, share it, discuss it, update it and keep working towards it.

7. Good UX design documentation provides clarity over quantity.

Amongst other typical UX deliverables, experience maps – for instance – look shiny and provide a lot of real estate for general research findings, brand touch points and service opportunities, but if the essence of such a ‘polished excel canvas’ can be communicated in two short, plain english paragraphs, on a sheet of a DinA4 paper – then do it that way. Jaimie Levy believes that these maps are just made to inspire people about why they are making their product on the way to the bathroom. (Source). If you happen to be working at an agency that is desperate to add those shiny design deliverable to their SOW and sell ~four more extra days of idle work to a clueless client, then you probably are working for an organization that puts their interest above the ones of their clients. I always say; product over powerpoint. Minimum description length over long blah-blah.

8. Good UX design documentation is illustrative.

Indeed, good design documentation should be illustrative, but never in a decorative way, like we discussed in section seven. Ask yourself; how can I present my design insights and research findings in the most tangible way? It does not have to be executable code. Why not search for similar solutions and best practices and screen record it, or provide a link if you are short on time? This will give anybody involved in the design- and development process a good idea of how the end-solution might look like. Animated gifs, like these are a great alternative, too. How about behavioural insights from qualitative user/customer research sessions? Why not invite people to tune into live research sessions and hear responses first hand, instead of sharing recordings and long reports with stakeholders of team members. Do a weekly podcast to share the most important snippets; you can add more depth in spoken words.

9. Good UX design documentation supports behaviour-driven development.

Download the poster with the 10 principles as PDF

As you get more involved in the execution of your design proposals and recommendations, start embracing the world of behaviour-driven development (BBD). BBD is best known to developers and is just a collection of tools and methodologies based on test-driven development. In BDD instead of writing tests you should think of specifying behaviour – which, as a UX designer you already do well. So start incorporating developer user stories, acceptance criteria and business rules, and write them down in Gherkin – to create an executable specification for the software you co-create with your peers.

10. Good UX design documentation is low effort and high impact

Embrace cutting corners, but wisely. I mentioned earlier it is important to avoid getting lost in decorating and over-designing your UX templates and research reports. It’s just a lot of time wasted! Also imagine ways you can get design- and research results faster. Maybe you’ve already implemented principle one and set up design and research streams that help you semi-automate some of your processes (hint: Zapier is your friend). Do whatever it takes to put yourself into a position that allows you to constantly produce and share updates. This will increase the impact you have in your company. First, get your ‘system’ to work, then focus on and tweak the outcome.

Last but not least – make your design docs popular as pie.

Got great ideas for UX design documentation? Share yours in the comment section.