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.

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”