The Kind of Documentation Users Really Want

Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce. But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Documentation>Usability>User Centered Design

Little Machines: Understanding Users Understanding Interfaces    

This paper questions the ubiquitous practice of supplying minimalist information to users, of making that information functional only, of assuming that the Shannon-Weaver communication model should govern online systems, and of ignoring the social implications of such a stance. Help systems that provide fast, temporary solutions without providing any background information lead to the danger of users completing tasks that they do not understand at all. (Word will help us write a legal pleading, even if we have no idea what one is.) As a result, we have help systems that attempt to be invisible and to provide tool instruction but not conceptual instruction. Such a system presents itself as a neutral tool, but it is actually an incomplete environment, denying both the complexity and alternative (and possibly improved) modes of thinking about the subject at hand.

Johnson-Eilola, Johndan. Journal of Computer Documentation (2001). Articles>Documentation>User Centered Design>Usability

Rethinking User-Centered Information Development  

Often in the computer industry there is a tendency to provide information about the features of a system. However, customers usually purchase the system based on knowledge of its features, when they receive the product they need information on how to accomplish tasks. Developing task-oriented information requires a shift in perspective from what the computer technology can do, to what your customers want to do with the technology. The resulting information must be usercentered rather than feature-driven. These types of customer requirements demand afresh development approach.

Stertzbach, Lori A. STC Proceedings (1995). Articles>Documentation>User Centered Design>Usability

User-Driven Documentation: From Usability Testing to User Guide  

Rockwell Software is a $90-million company specializing in plant automation software. Offices in West Allis, Wisconsin, and Mayfield Village, Ohio allow technical communicators to work closely with development teams to design, test, and release usable, consistent software and information products. While Rockwell Software’s information development process is a multi-faceted endeavor, this paper focuses on the following three steps we implement to create our information products: interviewing customers to establish information guidelines, conducting usability tests, and writing Getting Results guides.

Butler, Scott A., Jennifer L. Giordano and Myron M. Shawala III. STC Proceedings (1999). Articles>Documentation>User Centered Design>Usability

When Products Become Easy to Use, What's Next for Writers?

People who follow the right trends will someday lead them. Such an opportunity now lies in the hands of technical writers, as the computer field moves toward standardized, graphical, easy-to-use interfaces.

Oram, Andrew. Boston Broadside (1991). Articles>Usability>User Centered Design>Documentation

User-Guide-Driven Development

In my work with Bumblebee I use an approach I call 'User-Guide-Driven Development,' or UGDD for short. The mechanics of UGDD is similar to that of Test-Driven Development (TDD), but before I write the test for a feature, I write a snippet of the user guide describing the feature I am about to implement.

Brolund, Daniel. Thoughts of a Goldfish (2008). Articles>Documentation>Usability>User Centered Design

Documentation Usability: A Few Things I’ve Learned from Watching Users

Even though your customers may not read manuals, your tech support team probably does, which means someone is reading the manuals and using them to help others. But if your users find it easier to call someone, wait on hold for an agent, and then ask the agent a question rather than find the answer in the help, maybe your help materials aren’t very usable. Maybe increasing the usability of your company’s documentation could alleviate the need users feel to seek answers from another source.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Documentation>Usability>User Centered Design