Search results

New series: User-centered documentation

Series: User-centered documentation

by Tom Johnson on Apr 23, 2015
categories: user-centered-documentation

I'm starting a new series on my blog about user-centered documentation. If you're new to my blog, a series is a collection of posts (usually about 10) focused on the same topic. The series format gives me a chance to explore a topic in depth without publishing a monolithic post all at once.

Origins of user-centered documentation

User-centered documentation stems from user-centered design. With user-centered design, designers usually study their users in depth as they design products. Designers may do any of the following to get a better understanding of users:

  • Observe users in their own environment
  • Do task analysis to define the steps users take
  • Storyboard user workflows and goals
  • Do A/B testing with prototypes
  • Create personas that represent typical users
  • Gather feedback in usability labs, and more

The goals of user-centered design is to create a product that users love.

How user-centered documentation differs

With documentation, you could do all of the same techniques as with user-centered design. However, usually technical writers don't do this kind of in-depth user analysis for at least two reasons:

  • As a technical writer, you're not designing a user interface. Theoretically, the UI or other product has already been designed around specific user goals and workflows. The technical writer's job is to document how these user goals are accomplished in the product. As such, beyond simply understanding the user goals, you don't need to recreate all the usability work that already went into the product's design.
  • Technical writers aren't given this much time or user access to do all of this research.

I'm not saying it wouldn't be a good idea to immerse yourself in your users' environment, draw up personas based on salient characteristics, interview users about their goals and workflows, and observe them while they perform these tasks. In fact, if you do this, I'm sure your help would be really awesome.

But when these opportunities aren't available or feasible of your project, you can still create user-centered documentation by identifying common user behavior patterns and optimizing your help for those patterns.

Optimizing for user patterns

I've had the opportunity to observe users interacting with my help content in usability labs, and it's an eye-opening experience. If you have a usability team, you should definitely make friends with the researchers and squeeze in some documentation-related usability tasks.

Here are a few posts detailing notes from those usability observations, as well as other posts from watching users:

When you observe users, you notice some common patterns. If you design your help with those user patterns in mind, your documentation becomes more user-centered.

12 patterns of user behavior with help material

In looking over common patterns with users, as well as looking through various books on usability, I've decided to focus on 12 user patterns. These patterns aren't in any particular order, but I believe they capture the heart of user behavior when it comes to the way people interact with documentation:

  • Users are in a state of frustration/hurry.
  • Users gravitate toward visuals.

  • Users learn by doing.

  • Users read with an end goal in mind.

  • Users don't read in a sequential order.

  • Users don't want to leave their current context to look in the help.

  • Users scan and jump around.

  • Users have different technical abilities.

  • Users want simple instructions.

  • Each user might have a different way of organizing the same content.

  • Users start out in the application before moving to the help.

  • Users often search for answers with the “wrong” terminology.

Note that I'm not necessarily addressing physical products. I'm mostly talking about software documentation, since I've always worked with software.

Designing information to fit the 12 patterns

Based on these 12 patterns, we can design our documentation so that it optimally addresses these patterns. I'm not going to list ways to address the patterns in this overview. Instead, with each post, I'll list several strategies for taking the patterns into consideration.

Test your content with users

After optimizing your help with these user patterns in mind, the next step is to test your content with users. You don't have to do extensive testing, but you should do some kind of tests that involve users (even colleagues) using your documentation to see if they have a “delightful and pleasing” experience. Not testing help content is somewhat akin to not testing code.

Feedback welcome

During this series, I readily welcome any feedback. Do you think I'm missing any key patterns here?

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.