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 usability.gov.

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

Related

Contracting Creatives, in Brief

Your team has reached the stage where you need to hire a professional designer. Maybe you want to finally get a great-looking logo, make a website that doesn't look like it was designed in 1996, or create a really compelling video for your Kickstarter campaign. In any case, you know that it might be tricky to express what you're looking for – especially if you come from a technical background and aren't used to dealing with folks who work in pixels.

How to Sketch Storyboards in 10 Minutes: No Drawing Skills Needed

Sketching storyboards – cartoon-like drawings showing how people use technology – is a way to get more, high-quality ideas for product design. Sketches are useful for taking notes during a discussion and for getting a team on the same page. Fine art drawing is difficult for many, but anyone can master the basics of sketching storyboards – even without drawing skills. You don't need to be artistic, just follow these simple steps.

I Read About "Design For Trust"; So You Don't Have To

Here's the difference between the current "design for trust" discourse and how trust actually works.