Let's Stop Writing Documentation and Start Working for the Users  

Nearly 20 years ago, the profession of technical communication began to focus on developing task-oriented documentation. Although task-oriented documentation has always been produced, particularly for consumer products, it was not the standard in the computer industry. More often, people writing about computer systems focused on the system rather than on the tasks people needed to perform. Systems-oriented documentation was the norm.

ComTech Services. Articles>Documentation>User Centered Design

Let's Stop Writing Documentation and Start Working for the Users  

Technical communication's long-time focus on task-oriented documentation has left customers with too many tasks and too much information; itï¿Âs time for a new approach. A user-centered approach reflecting a thorough understanding of users and how they engage the product is the surest route to effective documentation and training. To understand what users need, we need to get closer to them by spending time in their workplaces, watching them execute everyday tasks, and listening to them. Through this kind of ethnographic activity, we will become user experts, gaining credibility within our own organizations and our user communities.

Hackos, JoAnn T. STC Proceedings (1999). Articles>Documentation>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

Making Help More Human, and Other Discussions

Discusses a number of trends in the technical writing world, particularly the need to make help more human by adopting conversational tones and addressing the angry/frantic state of the user.

Johnson, Tom H. and Heidi Hansen. Tech Writer Voices (2007). Articles>Documentation>User Centered Design>Help

Making Manuals Obsolete: Getting Information out of the Manual and into the Product    

Users loathe reading the operating manuals that accompany new equipment. Manuals often sit unused on a shelf, far from their targeted audience, while the costs of technical support soar. This article promotes integrating information traditionally found in printed manuals into the product itself and reports the experience of a design team in developing an easy-to-use product requiring minimal printed documentation. As part of design teams, technical communicators can advocate both reducing the amount of information required to operate a product and making the information immediately available when needed. These strategies can produce increased customer satisfaction and lower post-sales support costs.

Millar, Carol. Technical Communication Online (1998). Design>Documentation>User Interface

Managing Quality Graphic Design in a Documentation Project  

Supervising the design of documentation is challenging for documentation managers who have little or no educated knowledge of design. However, quality design that maintains ease of reading, accessibility, comprehension, retention, and aesthetics is vital to the usability and success of the documentation and should be carefully monitored by the documentation manager. Decisions must be made up front on four design areas -- packaging, layout, typography, and highlighting -- before the project is underway. In addition, audience analysis and a design style guide are two techniques that managers should embrace in supervising design.

Listeman, Amy J. STC Proceedings (1995). Careers>Graphic Design>Document Design>Documentation

Mental Processing of Online Documentation: From Concepts to Applications  

This panel will review the existing literature on how we mentally process online documentation and describe some implications for effective online document design. We invite the audience to define with us some critical areas for further research.

Knodel, Elinor L., Henrietta Nickels Shirk, Candace Sodetston and James Thibeau. STC Proceedings (1997). Presentations>Documentation>User Centered Design

A Millennial Paradigm for Documentation: the Scroll!

Although some zealots have proposed eliminating printed information entirely in favor of online help systems, Adobe Acrobat files, and even e-books, discarding printed books may prove less effective than simply modernizing them. Scrolls are the logical successors to books.

Hart, Geoffrey J.S. Geoff-Hart.com (2001). Articles>Documentation>Information Design

The Narrative User Interface  

Only a small percentage of users open Help, and they usually do that only when they have trouble with the application. One way to reach a broader audience is to integrate assistance into the user interface so that people understand the product as they use it. This paper describes our reasons for moving in this direction, provides examples of integrated user assistance, and discusses issues and concerns inherent in moving away from traditional Help.

Raiken, Nancy, Diane Stielstra and Richard Bloch. STC Proceedings (1998). Design>Documentation>User Interface>Help

New Life for Product Documentation

Here are some 'truths' we've all heard: 'Documentation is just a band-aid for poor design.' 'Real users don't read manuals.' 'Super users never read anything.' 'Help doesn't.' But are they really true? I've seen some signs of life in the use of documentation for digital products recently.

Quesenbery, Whitney. UXmatters (2006). Articles>Documentation>User Interface>User Centered Design

Non-Fatal Errors: Creating Usable, Effective Error Messages

It's often easy to identify what kinds of error messages don't help users, but it can be tricky to avoid them, and even more of a challenge to create the opposite: error messages that give users a clear indication of the problem, offer information to help them fix it, and provide tips on how to avoid the same situation in the future. This paper details the steps involved in creating understandable, helpful error messages, and suggests ways of communicating the value of good error messages to managers and executives.

Wilska, Emily. WritersUA (2004). Articles>Documentation>User Centered Design>Online

On My Little Planet...

Nobody reads user manuals for pleasure. And yet we all make our living from them, and hope that what we produce is at least useful, if not actually enjoyable

Bardez, Jean-Paul. TC-FORUM (2000). Articles>Documentation>User Centered Design

Online Documentation in Reference-Based Instruction: A Practical Model for Integrating Help Systems Into Product Training    

Companies can improve customer satisfaction while reducing training time and product support costs by integrating online documentation with product training. Online documentation can be designed to be not only the reference at the point of use but also the primary instructional medium used during training. This use of the online documentation during training increases user acceptance of it and helps develop the required skills for its use. This expanded role for online documentation provides new opportunities for technical communicators to add value to their roles within their companies. This article defines reference-based instruction and outlines its benefits. It describes how reference-based instruction can be incorporated into an instructional system design (ISD) and provides specific examples of learning objectives and student exercises. It lists guidelines for how to structure usability tests for Help systems, and finally, it advises how technical communicators can use reference-based instruction to ex

Hughes, Michael A. Technical Communication Online (1997). Articles>Documentation>Instructional Design>Education

Online Documentation: Design Issues

Designing online documentation? You mean I can’t just take the word processing file and make it available on our network, or throw the document into a Windows Help file and ship it? Well, I would not recommend either of those options. You should take many things into consideration when you design an online document.

TechCom Plus (1999). Design>Publishing>Documentation>Online

Online Help: Beyond Error Messages  

Knoth-Weber describes how her company developed an efficient means to collect customer feedback about system errors and publish solutions on their Web help page.

Knoth-Weber, Lieselotte. Intercom (2002). Design>Documentation>Help

Online-Dokumentation aus Anwendersicht  

Benutzerinstruktion muß sein. In Form von Online-Documentation ist sie unmittelbarer Teil des Programms.

von Obert, Alexander. Techwriter.de (1998). Articles>Documentation>User Centered Design>Help

Page Layout and Sample Designs in Full Color Manuals for Japanese Users  

Compared to American users, Japanese users have a tendency to prefer visually intensive manuals. This is especially true for the fill-color manual of the color copier which I am responsible for, as can be seen from the many requests and comments regarding the presentation of examples, how color is used, and the layout, It is my intent to introduce the tastes of Japanese manual readers by explaining the improvements that have been made to the visual aspects of the fill-color manual for one of our color copiers.

Mizukami, Rieko. STC Proceedings (1997). Design>Documentation>Document Design>Japan

Peaks and Pitfalls of Implementing a New Documentation Strategy  

In 1993, Compaq Computer Corporation ventured into a totally different market--the consumer market. Once known primarily as a company that manufactured high quality, expensive business computers through its elaborate dealer network, Compaq was faced with selling its units to consumers through retail outlets. As a result, the PC Marketing Communications department concluded that its current documentation set was not giving the students; retirees; homemakers; and small business owners, who work out of their home offices, the kind of information they needed to be productive. This led the department to the challenge of creating a new documentation set that would meet the needs of these new customers.

Clifton, Deborah, Deborah R. Crockett, Diana Jaques and Sharon B. Jones. STC Proceedings (1995). Articles>Documentation>User Centered Design

Persona-Based Documentation

InfoSourcing's Persona based documentation approach allows our technical writers to prioritize their writing tasks and document the product to end users, who is going to use the product ..."

Sarjapur, Harsha. Info Sourcing (2005). Resources>Documentation>User Centered Design>Personas

A Process for Creating Interactive Instructions  

In an undertaking such as the metamorphosis from printed instructions to on-line instructions, it is important to have a process in place. Relying on the process used by the User Interface Design Department at Thomson Consumer Electronics has helped my department remain focused and on schedule with the project. This paper briefly outlines the Consumer Information Design Department’s process for creating an interactive instruction manual prototype, and might serve as a guideline for others who may also be making the leap from paper to interactivity.

Lesandrini, Jay. STC Proceedings (1998). Articles>Documentation>Interaction Design

Putting Graphics Online: Avoiding the Pitfalls  

Online information is becoming more the norm today than paper-based materials with online Help a standard with most products and the proliferation of the Internet and intranets. However, putting graphics online can be one of your biggest headaches in an online project. This paper will introduce some of the issues you will encounter when putting graphic information online and make suggestions on how to solve them.

Cooper, Charles and Ann Rockley. STC Proceedings (1997). Design>Graphic Design>Documentation

Question and Answer Method of Generating Manuals  

Several Texas Instruments writing groups are using a new manual publication method that emphasizes more customer interaction early in the manual development process. This emphasis brings project teams and customers together to accurately define their expectations for the documentation. Writers chunk information as they create the manuals, which allows reviewers to look at the small pieces one at a time and to focus only on those chunks containing information pertinent to their particular expertise. This method defines manual parameters early in the process, which simplifies usability testing.

Lang, Darice. STC Proceedings (1994). Articles>Documentation>Information Design

Reader-Centered Documentation Provides the Necessary Context    

A features-based approach to documentation is appropriate for reference manuals, where the goal is to provide information on something the reader already knows. This article explores how to meet the needs of the reader when providing documentation for user manuals.

Hart, Geoffrey J.S. Intercom (2007). Articles>Documentation>User Centered Design

Restructuring Online Documentation for the World Wide Web  

Technical communicators around the world are turning to the World Wide Web us their primary delivery agent for on-line documentation. The transition from older forms of on-line documentation to HTML-based documents pre - sents new challenges in every phase of the documentation process: document creation, layout, access, and especially hypermedia capability The constant development of new web tools presents an even greater challenge for an organization seeking to stay abreast of technology with an ever decreasing budget. This panel will outline the basic steps in migrating to the web while focusing on one organization’s solution to meeting the challenges of restructuring its on-line documentation for web migration.

Goode, Christina M., Jennifer Campbell and David Hale. STC Proceedings (1996). Articles>Documentation>Web Design>Online