Effective User Assistance Design: Ten Best Practices

In a utopian world, a product would be so perfect it would not need any user assistance at all. But in reality, products aren't perfect, and users need assistance through different stages of their use. User assistance (UA)--in the form of manuals or online Help--guides users in their tasks, suggests better ways of getting their work done, and provides directions for troubleshooting their problems.

Dalvi, Meghashri. UXmatters (2007). Articles>User Interface>Help>Online

Electronic Documentation Basics

Below you can find a compilation of the most frequently asked questions about electronic catalogs. You will find answers to general as well as to technical questions.

ITEDO Software (2003). Articles>Documentation>Online>Help

Embedded Help – Meeting the Needs of Your Users  

Designing and developing an embedded help solution involves several stages. A successful solution starts with identifying user wants and needs. As you sort through these needs, identify common threads and design a solution that addresses these common threads. Consistency, flexibility, and experimentation are keys to developing a successful solution. Your design should be intuitive to use, and should provide users with the options they need. As you design your solution, consider your develop and maintenance requirements. You want the time you invest in the first version of your solution to pay off for future releases.

Mueller, Paul. STC Proceedings (1999). Articles>Documentation>Online>Help

The Evolution of a Help System  

An industry-wide design standard for help systems does not exist. To develop a flexible and usable help system for our workstation-based product, we have evolved and changed our help system design. Over a five-year period our help system was influenced by several factors:

Caldanaro, Regina M. and Michelle Corbin Nichols. STC Proceedings (1995). Articles>Documentation>Online>Help

Fault Tolerance: A More Forgiving Doc-To-Help and Word for Windows  

Doc-To-Help 2000 has a new 'fault tolerance' feature that forgives novice authors their Microsoft Word mistakes, including direct formatting and stretched bookmarks. These problems often cause corrupted cross-references as well as document-to-Help-system conversion problems. Doc-To-Help's automatic diagnostic and repair utilities now find these common errors and correct them automatically.

Wade, Jenny. ComponentOne (1999). Articles>Documentation>Online>Help

From Information to User Assistance: A Support System for a User Technology Organization  

Our plight as users of process information is much like that of the users of the information for our software products. Like them, we want to do useful work and get appropriate assistance when we need it. Instead of just reading about a task such as writing an information plan, we want the templates and samples to use when writing the plan. Just-in-time assistance, experience captured in a useful form, would suit us just fine. This paper, by the designers and developers of a system that supports the work and processes of a user technology organization, presents the information design issues that we encountered and the design of the system that we created.

Hargis, Gretchen, Deirdre Longo and Lindsay Bennion. STC Proceedings (1999). Articles>Documentation>Online>Help

From Online Help to Embedded User Assistance  

Online help systems have evolved over the past twenty years to meet the needs of our users. Designers must consider the content, format, presentation, navigation, and access methods of online help systems. A series of design checklists based on the past 20 years of research are presented in this paper, which summarizes a journal article currently being considered for publication. The latest trend in online help system design is embedded user assistance, which includes integrating information into the interface and including an embedded help pane within that interface to display a context-sensitive online help system.

Corbin Nichols, Michelle. STC Proceedings (2003). Articles>Documentation>Online>Help

Help Is Dead. Long Live Help!  

As Help Authors, we often treat online help as a 'thing,' not an activity. We’ve favored the noun over the verb! This preference is natural for writers, who enjoy producing books. If we hope to survive on a dynamic development team, we must train ourselves away from writing books, toward helping people. This shift means examining the bigger picture and adopting different ways of working.

Sisler, Paul and Catherine M. Titta. STC Proceedings (2001). Articles>Documentation>Help>Online

The Help Landscape: A Mile Wide and 30 Seconds Deep

Two questions any writer must deal with are: 'What do I write about?' and 'How much do I say about it?' Essentially, these questions deal with the scope and the depth of a document. Technical communicators have a tendency to want to document a topic as completely as possible, and we carry this instinct with us when we architect and write Help files. In this column, I challenge that prevalent instinct and offer an alternative way of thinking about the scope and depth requirements of Help systems. The benefits of this approach are, I hope, better Help for users and, for our clients and employers, a more efficient use of technical communicators' time. First, I'll discuss three principles that underpin my perspective, then I'll give some practical advice about writing Help that people will actually use.

Hughes, Michael A. UXmatters (2007). Articles>Documentation>Help>Online

Help! Six Fixes to Improve the Usability of Your Online Help  

Tight deadlines and limited resources often force wiiters to cut corners and release less than optimal help system designs. After considerable trial and error, I te come up with a checklist that can help you evaluate and improve your help system for the next release. Each question represents an important usability issue.

Timpone, Donna. STC Proceedings (1997). Articles>Documentation>Online>Help

Hero Stuff: Saving 50% on Support Costs with Fax and Modem Support Documents  

In the PC products market, customers insist on excellent support at rock-bottom prices. The traditional model of customer support, having a phone technician answer customer questions, is becoming too expensive.

Brown, Constance C. STC Proceedings (1993). Articles>Documentation>Online>Help

HTML-Based Help: A Convergence of Two Solutions  

IDX Systems launched two separate HTML-based help authoring efforts simultaneously. The results were two very different HTML-based help solutions. One solution emphasized thorough and complete information while compromising accessibility. The other solution emphasized accessibility while compromising thoroughness and completeness. In both cases, the compromises were forced by the limitations of current web technologies. The two writing efforts have now been merged into one solution that uses HTML, database technology, and Active Server Pages.

Johnson, Wayne and Fritz Garrison. STC Proceedings (1998). Articles>Documentation>Online>Help

Implementing Help Systems for Java Applications  

Technical communicators are facing a revolution in how we develop online help for software applications. No where is this more apparent than in the development of help systems for applications written in Java. Sun Microsystems, Inc., expects to roll out JavaHelp in the early part of 1998. Until JavaHelp arrives, technical communicators will have to find creative ways to implement HTML help systems for Java applications. The best news is that we have some standards to follow, like HTML, and some methods for browsing HTML help today. The key is to develop scalable help systems designed with the future in mind. This paper discusses some ways you can create HTML help content that works with your applications today and tomorrow.

Colvin, Richard D. STC Proceedings (1998). Articles>Documentation>Online>Help

Indexing Online Help  

In order to make a help system really helpful, you need to provide an effective index. But many online help writers face two dilemmas when it's time to index their help systems: How to prepare a useful index that meets the users' needs and how to code the keywords to make the index compile correctly. This article provides tips to help writers solve both problems.

Hamilton, Beth. STC Indexing SIG (1999). Articles>Documentation>Online>Help

Indicating Changed Text in Help Files

There are still many circumstances when drawing a user's attention to changed text is important. How do we do that with Help systems? By borrowing techniques from paper manuals, we don't have to reinvent the wheel. So here's a good approach that will work for Microsoft Word-based HATs.

Self, Tony. HyperWrite (2004). Articles>Documentation>Online>Help

Instructional Text in the User Interface: Some Counterintuitive Implications of User Behaviors

User assistance occurs within an action context--the user doing something with an application--and should appear in close proximity to the focus of that action--that is, the application it supports. The optimal placement of user assistance, space permitting, is in the user interface itself. We typically call that kind of user assistance instructional text. But when placing user assistance within an application as instructional text, we must modify conventional principles of good information design to accommodate certain forces within an interactive user interface. This column, User Assistance, talks about how the rules for effective instruction change when creating instructional text for display within the context of a user interface.

Hughes, Michael A. UXmatters (2007). Articles>User Interface>Help>Online

Interactive Help: Adapting Content for Multiple Users  

Most online help systems present a 'one-size-fits-all' solution—fixed content for each topic—but users’ experience levels and backgrounds are complex and diverse. Users lose time and patience sifting through topics that either do not match the problem a user is trying to solve, or that present information that does not match a user's knowledge level. A group of Masters students at Carnegie Mellon University tackled this problem. As a course project, the team created an online help prototype that contains different levels of help, a prototype that gives users a choice about how much information they want to see.

Downs, Christina M. and Anne F. Jackson. STC Proceedings (2001). Design>Documentation>Online>Help

Issues in Designing, Implementing, and Evaluating a Help System  

The design team for a major new product approached our publications group about ideas on developing an online manual and/or online help. Together, we developed a task-oriented, easy-to-use online help system, and continue to work together to evaluate it. Where do we best put the buttons that access the help for various subsystems?

Evans, Jeanette P. STC Proceedings (1993). Articles>Documentation>Online>Help

Key Roles In Developing Successful Online Help  

There are many roles involved in developing a successful online help project. Understanding the relationship between these roles can increase everyone's awareness of the requirements and tasks necessary for a successful project. In many projects, individuals fill more than one role, moving between roles as needed.

Hall, Rebecca C. STC Proceedings (1999). Articles>Documentation>Online>Help

Low-End Online Documentation Viewing Systems: Why and How  

Online documentation is now widely accepted for its convenience and cost savings. However, some small, non-Windows shops find very few offerings in the market place for online documentation software.

Sonnenberg, Beth Apple. STC Proceedings (1995). Presentations>Documentation>Help>Online

Making Online Help Helpful -- Perspectives of Professionals and Users  

This paper reviews research done in online help information, analyses different views on it from the perspectives of professionals of technical communication and end-users, and suggests ways to solve problems.

Li, Yue. STC Proceedings (2003). Articles>Documentation>Online>Help

Mastering the Mayhem: How to Manage a Hypertext Help Project  

Two main forces affect a Help project: absurd deadlines and a complex web of hypertext files. Those responsible for managing such projects often ask: How do I gain control of all these forces? When do I need to start the project? How do I gauge its progress? Our demonstration will show how to successfully manage a Help project. We will illustrate how WordPerfect Domestic Documentation Services solves management problems using a timeline, checklist, and tracking database.

Calhoun, Deirdre and Wendy Fritzke. STC Proceedings (1994). Articles>Documentation>Online>Help

Maximizing Windows Help  

Maximizing Windows Help is more than just converting printed documentation to Help. Help users want easy access to information so that they can complete their tasks expeditiously. A Help topic should contain information that adresses one subject, has one objective, and answers one question. To maximize Windows Help, chunk information and use hyperlinks. The use of macros can enhance how information is accessed.

Smart-Wycislo, Nicole Y. and Patryce Moshay. STC Proceedings (1997). Articles>Documentation>Online>Help

Migrating to WinHelp 4.0 for Windows ’95  

WinHelp 4 is the help environment for Microsoft’s Windows 95 and Windows NT operating systems. Among the important new features of WinHelp 4 are more capable secondary windows, shortcut buttons, the ability to integrate multiple help files, What’s This? help, and better support for online coaches. Help authors must understand both the construction and the design aspects of these new features. They must also deal with the complexities of the transition from Windows 3.1 help to WinHelp 4.

Farkas, David K. and Joe Welinske. STC Proceedings (1996). Articles>Documentation>Online>Help

A Modular Approach to WinHelp Projects: The Process Behind the Success  

The Knowledge Products group at Cisco Systems, Inc., provides online help for both PC and UNIX-based applications. The online help team for the Cisco Works for Windows product comprised of five writers who coordinated the online help development efforts. The online help team worked closely to produce an integrated help system that was modularized for better process control.

Mandavilli, Lavanya K. STC Proceedings (1996). Articles>Documentation>Online>Help