Search results

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.

Usability labs have a mirrored glass that lets you observe users without them realizing they're being watched.

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.

Universal Principles of Design

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

Organizing content

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.

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.