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”