Introduction to User-Centered Documentation

Recently I gave a two-hour workshop about user-centered documentation to a company. You can view the slides here:

I decided to convert the presentation into a User-Centered Documentation course on my site (similar to my API doc course).

Rather than populating the course page by page, I instead pasted the content from the presentation into different pages as a skeleton outline for the course. You can navigate the pages using the sidebar on the left.

My plan is to go through the 20 or so pages in the course and fill in the details with narrative, background, examples, and other detail. I’ll be working on this through 2017. For now, though, you can get an idea of the course from the skeleton outline.

Observations in Usability Labs

You can learn a lot by watching users in usability labs. At a previous company, we had a usability lab and did some testing with help docs for about a half dozen users.

I gained some good insights from these usability sessions. For example, beginning users prefer video. Advanced users like to skim text.

However, these insights were drawn from a small number subjects. It could take years of observation to arrive at a core set of design principles that would be thoroughly tested across many different documentation scenarios and demographics.

Rather than try to reinvent the wheel by launching thousands of usability studies focused on documentation, I decided instead to piggyback on known design principles. There are already an abundance of known, researched, universal principles of design that have been validated time and again. We can simply apply these general principles to documentation scenarios.

Universal Principles of Design

To leverage existing principles of design, I draw upon a subset of design principles from Universal Principles of Design, by William Lidwell, Kritina Holden, and Jill Butler.

This book has more than 125 design principles. I read through them all and selected about 20 that seemed most relevant to documentation scenarios. I inserted the principles with my own wording and slant towards documentation.

Applicable Design Principles

The following are the most applicable design principles to documentation. I’ve grouped them into two main categories.

Creating content

• Readability
• Legibility
• Signal-to-Noise Ratio
• Picture Superiority Effect
• Performance Load
• Personas
• Normal Distribution
• Design by Committee
• Depth of Processing
• Iteration

Organizing content

• Modularity
• Hierarchy
• Five Hat Racks
• Progressive Disclosure
• Entry Point
• Desire Line
• Wayfinding
• Immersion
• Consistency
• Forgiveness

You can browse through the brief course pages using the links in the sidebar on the left.

The Universal Design Principles book covers each principle brief in a few pages, with links to more reading. Additionally, the principles are in no particular order (they’re listed alphabetically).

Also note that the authors do not explicitly tie these design principles to any particular domain (such as documentation). These universal principles of design have a sense of being cross-domain in their applicability.