How to improve the UX of your documentation

Many projects we work with involve new, unusual or complex technologies, and it is challenging to present information about the tool that respects both beginners and experts alike. This problem is especially difficult when it comes to the documentation.

Documentation serves many different needs. For first-time users, it is the place that provides guides and manuals for your initial set-up and onboarding. After successfully setting up the tool, many users will likely never return to the documentation again. If you have contributors to your tools, e.g. from developers, translators, writers, and others, it is a place people go to understand the technical specification, tweak or extend their set-up, or potentially even develop an interoperable service. When these groups of people meet in the same place in the documentation, they might get frustrated and confused, and work around your carefully documented process to find their own solution if the documentation isn’t clear and approachable. In extreme cases, this can present a security risk, as it did with the case of developers copying code from Stack Overflow instead of reading the documentation.

When you work in an environment that regularly tells people to RTFM*, it’s really important to get the documentation right. Good documentation is skimmable, up-to-date, and thoroughly tested by its audiences. What’s more, good documentation is easy to navigate, and helps people find the relevant information quickly. This is where working on the information architecture of your documentation comes in.

We’ve made a quick design exercise to help you figure out who needs to know what, and what’s missing from your documentation so far.

  • On post-it notes or cards, write the titles of the pieces of information about your tool you already published -- for example: a glossary, what to do if you found a bug, how to install…
  • Think about, and write up, three different use cases or personas: first-time users, general users, and power users. Arrange these cards near the user they most apply to.
  • Is anything missing? For each users, write what’s missing on a different color post-it.
  • Within the clusters for each user, what’s the natural or appropriate sequence of these cards?
  • Reorganize your documentation according to the cards. For first-time users: use diagrams and visuals, define terms they might not know. For power users: use action words to organize your sections, for example: "set-up self-hosted version", "report a bug", "test the latest version".

Card sorting exercises can seem simple or boring, but are an extremely effective way to help you sort your information. Sometimes the best interventions are the simplest ones!

Here is an example of using card sorting to simplify and organize Tails’s documentation.

To learn more about the theory and practice behind documentation writing, we highly recommend the Write the Docs community and their guide for beginners. To learn more about card sorting, visit the tools section of

*an elegant way of spelling “read the f***ing manual”


Human-centered Design, Where to Start?

Instead of learning methods and tools, you can start by developing a design mindset. From our video series, Design Spots.

Keeping Everyone Safe: Quick, User-oriented Problem-solving with Mapeo

This fall, we had the pleasure of working with Digital Democracy on their application, Mapeo. Mapeo is a mobile and desktop app that enables indigenous communities to map their lands, sites, and resources, as well as record and monitor environmental and legal abuses by corporations and the state. The app is used by communities around the world, and due to the sensitive nature of the data being recorded, contributing to Mapeo can be high-risk for users. Our design challenge focused on user safety: how to protect end users in the likely event that a community mapper’s phone is lost, seized, damaged, or stolen.

A Curated List of GDPR Resources

GDPR is around the corner, and here are our best tips.