What readers want at stc17
This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.
Yoel Strimling presented a session titled “So You Think You Know What Your Readers Want?” He presented the results of a study that measured and compared how writers and readers define documentation quality, as well as how writers assume readers define it.
Yoel started by quipping that the most important word in the docs word starts with an F and ends with a ck: … Feedback.
The most important thing for good documentation is to know how well our docs work. For that, we ideally need direct, actionable feedback from readers. We have personas, user stories, use cases, journey maps – to make educated guesses. That’s not the same as actionable, direct feedback.
The definition of doc quality must:
- Come from a reader’s point of view.
- Be based on empirical, research-based feedback.
- Use clear and unequivocal terminology.
- Cover all possible aspects of quality.
Yoel found a study from 1998, based on 100s of interviews with information consumers, to find out what they wanted from their information. They came up with a framework for defining information qualities based on 4 categories: intrinsic, representational, contextual, and accessibility. Those categories were subdivided into 15 dimensions. Yoel talked us through an amusing illustration of these dimensions, to determine the relative quality of two pens. Part of this illustration involved losing his pen, which was tucked behind his ear!
Conclusion: To be of high quality, docs must be intrinsically good, clearly represented, contextually appropriate for the need, and accessible to the reader.
Yoel then created a survey, asking readers to rank the docs based on the 15 dimensions. He sent another survey to writers, asking them how they thought readers would rank the docs based on those same dimensions. The top results were very similar to each group:
- Top qualities as judged by readers: Accurate, easy to understand, and relevant.
- As judged by writers: Relevant, accurate, easy to understand.
But Yoel found 5 dimensions where writers significantly underestimate the value of the dimension to readers. In particular, writers underestimate the quality named “value to readers”. “Valuable” means “beneficial and providing advantages from its use”. Readers want us to give them docs that help them do their job better!
How do we help users to do their job better? Yoel asked the audience. These were some of the suggestions:
- Make the tools and the docs easier to use.
- Provide tips.
- Give the users the simplest flow, and avoid bombarding them with options.
- Pare down the information.
- Base the docs on the readers’ goals.
- Provide videos and graphics.
- Give the wider context when relevant.