Customer Partnering: Data Gathering for Complex Online Documentation  

Technical communicators today must document complex applications used in complex environments. Information about users and use models is important under these conditions, especially if documentation will be presented online. Customer partnering, a method of information gathering that supplements surveys, contextual inquiries, usability testing, and interviews, provides a way of involving the users of complex applications in the design of information delivery systems. We used this method to help a client gather important information about user and use models and design a new information library for complex server computer systems.

Hackos, JoAnn T., Molly Hammar and Arthur Elser. ComTech Services (1997). Articles>Documentation>User Centered Design>Collaboration

Defining Information Architecture Deliverables

One of the hottest topics these days in Information Architecture circles is documentation. This is probably partly because the IA's role is so ill defined. Our jobs sit perched between engineering and graphic design: go too far in one direction, we're doing the coding, go to far in the other and we are doing the design. Neither role maximizes the architect's key skills; defining the organizational structure and behavior of the web site or application. An IA is most effective when they leave implementation and final graphic design out of the mix. The documents they create to express this have to be crafted with equal skill and diplomacy.

Wodtke, Christina. SitePoint (2001). Articles>Information Design>Documentation

Designing a Help System for a Web Site

When I worked for a large insurance company, my team as tasked with re-designing the customer service area for a external Web site that supports annuities and mutual fund customers. I proposed redesigning the entire site including an actual help system (like with ones you can create with RoboHelp) to reduce customer service support calls. I was really surprised that everyone thought this was such a novel idea -- I thought it made perfect sense. Then, it hit me -- you don't see a lot of help systems for Web sites.

Leonard-Wilkinson, Theresa A. W-edge Design (1999). Design>Web Design>Documentation

Designing Effective User/Training Documentation with the Learning Style Inventory (LSI), the User Empowerment Inventory (UEI), and Think-Aloud Protocols  

While there are many instruments that measure the capacity for establishing peer-level communication skills, few exist that evaluate the effectiveness of knowledge transfer in the writer-reader relationship. The Learning Style Inventory (LSI), the User Empowerment Inventory (UEI), and thinkaloud protocols help assess how people acquire new knowledge and process information. The results of such measurements/ observations help determine user requirements. This paper presents a case history of how the LSI, the UEI, and think-aloud protocols helped improve both user and training documentation to a technology-averse audience in a reactive project environment.

LeVie, Donald S., Jr. STC Proceedings (1996). Design>Documentation>Methods>Usability

Designing Embedded Help to Encourage Inadvertent Learning    

What do we do when a legacy help system has trained the users not to use it? How do we design a solution that not only lures users back to the user assistance, but also encourages users to learn more about the product? This article follows the decision-making process of a design team that had to solve these problems. Additionally, the design team had to craft solutions for an application that imposed extreme limitations on those solutions, both in help system implementation and information design.

Mobley, Karen L., Clinton Knight and Timothy Meserth. Technical Communication Online (2003). Design>Documentation>Help

Designing for Interactivity: Role Models, Guides, and Coaches  

This paper presents three methods of user assistance: role models (simple demonstrations), guides (structured walk-throughs), and coaches (active assistants). After a brief introduction, potential uses, available development tools, and additional information sources are discussed for each method.

DeLoach, Scott. STC Proceedings (1998). Articles>Documentation>Help>Interaction Design

Designing for the Web: Special Considerations for Safety Information  

Manufacturers are currently grappling with determining whether they should put safety information on the Web and if they do how it should be presented. Technical communicators, Web content developers, and Web designers will ultimately be responsible for the presentation of Web-based safety information. This article discusses special considerations that should be given the formatting (HTML, PDF, etc.), design, (font, size, and color), and location of safety information on the Web. Additionally, areas for future research on the issue of Web-based safety information are identified.

Tallman, Lisa A. STC Proceedings (2001). Presentations>Web Design>Documentation

Designing Help Text

In an ideal world help text would be unnecessary - users would never get stuck in an application or site. It should be enough to provide clear design, carefully chosen titles and labels for the various functions, appropriate field prompts when user entry is required, helpful feedback, a glossary, and 'embedded' help such as default values, example input, on-screen step-by-step instructions and explanatory text next to fields or functions. Help features should certainly be a last resort. Anyone embarking on adding it to an application or site should be sure that they have already followed the best practise listed above. In most cases (certainly online) a help option should not be necessary.

Farrell, Tom. Frontend Infocentre (2001). Design>Documentation>Help>Online

Designing Object-Oriented Documentation  

Describes how to construct documentation using the object-oriented model.

Beg, Visja. Intercom (2000). Design>Documentation

Designing User Assistance for Internet Marketplace Applications Using Server-Side Online Help    

In this article, I examine Internet marketplace applications and the challenges they present to user-assistance design. This examination illustrates the ways in which complex Internet applications, such as marketplaces, force technical communicators to rethink their approach to online user assistance. In the course of this examination, I make a case for a model of user assistance that taps the potential for customizability, scalability, and dynamic content of the technologies that power Internet applications. However, marketplaces are only one example of the type of application that can benefit from this model because it can be implemented for any Internet or intranet application that utilizes dynamic, build-on-the-fly Internet technologies, such as Microsoft Active Server Pages or Sun Microsystem JavaServer Pages. To fulfill our responsibilities to our users, we technical communicators must be willing to expand our skill set by adopting these technologies that allow us to target documentation to user needs.

Whittemore, Stewart. Technical Communication Online (2003). Design>Documentation>Online

Developing a Single-Sourced Online Help System    

The definition of single sourcing continues to broaden in scope since its first mention in The Society of Technical Communication’s 46th Annual Conference publication. As a result, it is becoming increasingly difficult for technical communicators to understand what single source means and, more importantly, choose a definition of single sourcing that correlates with their specific task. One “type” of single sourcing involves reusing information for multiple products. Several developers at IBM have produced a single-source online help system. Unlike other single-sourcing methods that require a significant investment and a high degree of technical experience, these methods are inexpensive and require a moderate, yet creative, technical aptitude.

Vicek, Keith, Phil Menzies and Andre Evans. STC Proceedings (2002). Design>Documentation>Single Sourcing>Online

Developing an Embedded Help Solution    

As we grow up, we learn to develop our independence and to ask for help less and less. No wonder that, when confronted with a problem, so few users click the Help button. Standard help systems have several common issues: help is separate from the product; users have to leave the task they are performing to get help, and they return and try to remember what they were doing; users cannot find the required information; users get lost in the help.

Mueller, Paul. Technical Communication Online (2003). Design>Documentation>Help

Developing an Information Strategy  

The role of the technical communicator has been changing dramatically over the past few years. Gone are the days when hefty user manuals are considered desirable. Technical communicators must now think of ways of building intuitiveness into products to obviate the need for reams and reams of hard copy documentation. This understanding forms the basis for developing an information strategy.

Florsheim, Stewart J. STC Proceedings (1997). Design>Documentation>Information Design>Content Strategy

Developing Help for the Web: Designs, Trends, Strategies  

Zubak reviews the current state of Web-based help technology. Her article prepares technical communicators for upcoming challenges in this increasingly important field.

Zubak, Cheryl Lockett. Intercom (2001). Design>Documentation>Help

Differentiating Online Help from Printed Documentation  

Hemmi discusses the differences between online help and printed documentation and suggests how technical communicators can make the most of both media.

Hemmi, Jane A. Intercom (2002). Design>Documentation

Do Users Use a User Guide?  

Technical writers make distinctions between the types of documents they create: user guides, reference manuals, tutorials. But do users really understand these document types? How do users look for different kinds of information--and how do we, as technical writers, make it clear to them what types of information are available? This paper presents results of usability evaluations of documentation for electronic design automation software, showing how a writing team tried to improve the categorization and presentation of document types.

Heninger, Barbara L. and Michael J. Miller. STC Proceedings (2004). Articles>Documentation>User Centered Design>Genre

Do Your Manuals Put Children in Danger? A Survey of Juvenile Products Consumers  

What can manufacturers do to improve the readability of manuals that accompany juvenile products?

Manual Labour (2003). Articles>Documentation>User Centered Design>Children

Doc or Die

This blog discusses documents and information designs “in the wild" - especially those that are exceptionally good or exceptionally bad.

Doc or Die. Resources>Documentation>Information Design>Blogs

Document Design: A Brief Primer  

Today's documentation must be designed with information retrieval as its key objective. When information is organized and mapped into a consistent, logical structure that uses retrievability aids such as labels that facilitate scanning, blocks of information, advance organizers for the information, keywords, meaningful indexes, and a hierarchical organization, readers can quickly locate and use the information that they need.

Flanders, Melanie G. STC Proceedings (1997). Articles>Documentation>Document Design>User Centered Design

Document to the Question: Understanding What Users Ask and Where They Look for the Answers  

The user's idea of the problem is often very different than the help or program designer's. The online help topics often reflect the designer's viewpoint, not the user's.

STC India (2003). Articles>Documentation>User Centered Design>Help

Documenting in N-Dimensional Space

As technical communicators, we are being challenged with how to structure information in a multiple dimensional space made possible with Web technology.

Albing, Bill. KeyContent.org (2005). Articles>Documentation>Information Design

Documenting Networks

Documenting networks is playing less with words, and more with diagrams. It also requires an engineering mind, an ability to think out-of-box, and creative mind. Technical writers can rise to a new scale and expand their skill sets if they are able to document networks.

EDITsphere (2007). Articles>Documentation>Intranets>Graphic Design

Documenting Schemas  

The issue of documenting schemas—or any machine readable language—goes beyond simple additions of comments. Thereal challengeistocreateschemasthat arereadablebothdirectlybylookingat their sourcecodeandbydocumentation extraction tools.

van der Vlist, Eric. O'Reilly and Associates (2001). Articles>Information Design>XML>Documentation

The Effects of Motivational Elements in User Instructions    

Should instructional texts be purely technical, with a focus on effectiveness and efficiency, or should they also focus on satisfying and motivating users? Good arguments have been made for paying attention to motivational aspects. But only analyses of existing instructions have been published so far, and guidelines for making user instructions motivational have not yet been studied carefully. This article presents motivational strategies and an experiment to test their effects. The results show that motivational elements have little effect on users’ effectiveness and efficiency in performing tasks, their product appreciation, and their self-efficacy, but they do increase users’ appreciation for the instructions.

Loorbach, N., Steehouder, M., Taal, E. Journal of Business and Technical Communication (2006). Articles>Documentation>Rhetoric>User Centered Design

Electronic Catalogs: Graphics    

A compilation of the most frequently asked questions about graphics in electronic catalogs. You will find answers to general as well as to technical questions.

ITEDO Software (2003). Design>Documentation>Graphic Design>Online