“Great newsletter, Tim! I have to write a presentation for an industry conference next Tuesday. I’m suddenly happy that I haven't yet started, because your article gave me a lot of great ideas for how to structure my talk.”

—Robert Hopkins, Jr., President, Weblations

Have a comment? Send me your feedback.

User Assistance (UA), also known as “documentation” or “help,” is common for Web-based and desktop software applications; server utilities and applications used by network, database, and security administrators; hardware products; and medical devices. UA isn’t just a “doc” issue; it is an essential resource for your customers and a significant cost-saving measure for you—better UA for customers results in fewer calls to your help desk and fewer costly, onsite support visits. In fact, creating outstanding UA for your customers can make the difference between approaching and actually achieving your goals for customer satisfaction and retention.

This issue discusses these essential UA topics:

Welcome to Focus Forward, the monthly newsletter of Tim Rosa Associates. If you like what you’re reading, stay with us. You can also forward this newsletter to a colleague by clicking the Forward email link at the bottom of this newsletter. If you don’t like what you see, go to the same location, and click SafeUnSubscribe™.

As we said, user assistance is more than just documenting how your software or hardware works, because it’s really an extension of the product experience. If your UA materials are as easy-to-use and powerful as your product, you’ll only enhance your relationship with the customer. If your UA materials are mediocre, it will send the wrong message to your customers, and could detract from the real value of your solution. After all the investment you’ve made in development, quality testing, marketing and sales, it only makes sense that your UA materials support and even enhance these efforts.

User assistance comes in two principal flavors:

• “What is” information or “conceptual UA”
• “How to” information or “procedural UA”

Most UA includes some of each type of information. Common UA examples include use’s guides; online help systems; getting started guides; tool tips or balloon help; installation guides; administrator’s guides; API references; developer’s guides; wizards; and Flash MX-based movies.

UA is typically targeted to a particular segment of users that fall somewhere in the range from ...

and...

Conceptual UA provides the “big picture” of an application, system architecture, or installation. By contrast, Procedural UA is organized and written in a task-oriented manner, using discrete procedures with numbered steps that users follow to achieve a desired result. Content, format, and level of formality in communication vary widely. The style, tone, length, and type of presentation depend on the expertise of the intended audience and how critical the task is. For example, formal, precise, and highly-tested procedures would be used in UA for dispensing fluid from an intravenous drip, while UA on a game website might be less formal, but just as precise and technical for advanced users.

In considering changes to existing UA materials, or when creating new ones from scratch, it’s critical to evaluate your efforts against industry best practices. We’ve read, edited, and written thousands of UA materials over the years, and recommend the following best practices to our clients:

• Concepts and procedures should contain information and tasks targeted to the intended audience at the right level; while a software developer may have written the code, she may not be the right person to explain procedures to even the most advanced user. Use the person with the writing skills that fit the task.
• Presentation of the UA must be clean, professional, and appropriate for the intended audience. The page or screen layout should invite users to use the UA but should not interfere with their ability to get their job done. Be sure to rely on graphic design professionals with specific experience in the UA materials you need.
• Users should easily understand the context for the information easily and should be able to make their way through procedures without getting lost. Usually, the difference between good and great is in the quality of the testing and your choice of editor.
• Users should know ahead of time what the outcome of a task will be, and what they must do to prepare for the task. It can be frustrating to follow a recipe only to find out that you’re missing a key ingredient. Writers need to work with marketing and sales to understand the customer experience and tune the UA materials appropriately.
• Users should have a way to gauge their progress at every step and should be able to recover if they make mistakes along the way. Experienced writers know how to develop quality UA that takes these concepts into account.
• Navigational aids for the UA must enable users to quickly find information they need. For printed or online books, navigational aids should include a table of contents, running headers, and an index; online and Web-based help require browseable books with linked topics, browse sequences, and an index. Most software engineers, marketing writers, and quality assurance workers are inexperienced with developing these aids. Today’s UA professionals work with such aids on a day-to-day basis, and can advise you on the most appropriate approach.
• Blaise Pascal once said: “ I have made this letter longer than usual, because I lack the time to make it short.” Text should be short, precise, and technically accurate. A combination of left- and right-brain skills is clearly a requirement for the UA writer.
• Editorial standards must be applied consistently across all UA components. It’s much easier to work with a set of UA components if the tone, style, and level of writing are uniform.

Who Should Write the UA?

While some UA is written by software developers, product managers, or customer/technical support personnel, these individuals are not always the best-qualified for this activity. The most effective UA is written by technical communicators, seasoned professionals who know how to:

• Put themselves in the position of users—your customers—and define the key tasks that they need to accomplish with a software application, piece of computer hardware, or medical device.
• Review source material provided by engineering, product management, sales, and marketing to identify how best to present the product.
• Communicate with subject matter experts to uncover details about how the product works.
• Organize disparate information into real-world tasks that users will perform with the product.
• Write in a clear, precise, and consistent style.
• Solicit and integrate timely and relevant feedback from different types of reviewers—editorial, technical, and marketing.
• Define and follow a predictable process for meeting all deadlines and deliverable requirements.

User assistance materials are an extension of your company’s product, and as such should reflect the same level of technical expertise, innovation, and talent you’ve delivered in the product itself. Superior UA materials bring significant benefits to your company, because they:

• Showcase your company’s commitment to improving customer satisfaction.
• Enable new users to learn how to use your product easily.
• Provide fingertip reference for experienced users.
• Minimize technical support calls.
• Shield your software engineering staff from answering technical support questions.
• Increase customers' product knowledge so they can act as local experts within their own organizations.

For these reasons, engineering, marketing and product managers need to integrate UA material planning into every product roadmap. By developing high-quality UA materials that meet the specific needs of your users, you can enhance the overall customer experience and reduce your long-term costs.

Tim Rosa Associates is a team of senior-level technical writers, editors, proofreaders, graphic designers, usability experts, user interface specialists, and web developers. We staff our project teams with people who understand your technology and your business. Using our industry-proven 3-D Process—Define, Develop, Deliver—we create targeted user assistance for clients worldwide ranging from start-ups to the Fortune 500. Our clients are in the technology, healthcare, and financial services industries, so we understand the market pressures of competition and the requirements of global regulatory agencies.

Thanks for reading,
 

trosa@timrosaassociates.com
617.332.7895

Focus Forward Copyright © 2004 Tim Rosa Associates. All rights reserved.