Designing a Software User Assistance System

This article looks at a methodology for developing a software user assistance (UA) system in a structured manner. The software UA system could have both paper-based user manuals and online help systems.

Ferris, Tamara. Indus (2006). Articles>Documentation>Online>Help

Designing and Writing to Reduce User Errors  

A vast majority of documents (I consider print and online as documentation) often works to define the optimized error-free method of performing a task and provides a user with a straightforward solution. However, the user expects documentation to help solve problems and address errors. Thus, attention must be paid to potential problems users can have and how to correct them. Errors have different causes; the information designer should understand the potential types of errors since properly addressing each type requires a different approach in the design and documentation.

Albers, Michael J. STC Proceedings (2003). Articles>Documentation>Writing>Technical Writing

Designing Documentation for Visually-Impaired Users  

Preparing 'large-print' texts requires more than changing type size; it involves writing and structuring materials to meet the needs of an audience with varied physical challenges. For large print documents, format considerations include: using appropriate type, line length, and other design elements; setting all material flush left; and using lay-flat bindings. For braille documents, text may also need to eliminate or explain unusual symbols. Content considerations for both may include: replacement of graphics with descriptive text: brief orientation to the physical location and dimensions of objects; and reminders of help services. Cassette tapes offer one alternative to print or braille texts, plus serve other audiences.

Barthel, Brea. STC Proceedings (1994). Articles>Documentation>Accessibility

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 Information for the Online Medium  

Well-designed online documentation exploits the medium to make the content more accessible and effective. Knowing who needs the information and understanding when and how much of it will be used are essential for the creation of effective online content. Ideally, online documentation should answer each question with just the right amount of depth and detail. Considering user expertise, information needs, and usage patterns before creating the content or structure results in information that can be scanned, searched, surfed, referred to, read, or printed equally effectively—exactly what people expect from online documentation.

Mehrotra, Rahul and Jane Nye. STC Proceedings (1998). Articles>Documentation>Online

Designing Installation Manuals Used in Various User Environments  

Manuals normally contain information regarding all the functions of a given product. Therefore, there are cases when information required by one user is useless to other users. As a typical example, for users, performing a version upgrade, the upgrading procedure is important, but the procedure for new installation is useless information.

Shimosaka, Yuji. STC Proceedings (1999). Articles>Documentation

Designing Online Help for Pocket PCs

Advances in technology in the last ten years have created an emerging category of portable online computers (Pocket PCs or PPCs) that offer a wide range of product features comparable to Personal Computers (PCs). Improvements in PPC hardware specifications and the growing numbers of compatible software applications are resulting in an increased (and multi-faceted) user base. Increasing technical capabilities, advanced product features, and a diversified user base are creating new challenges to design online Help systems that can satisfy user needs and requirements effectively.

Natarajan, Prashant. Usability Interface (2004). Articles>Documentation>Help>PDA

Designing Usable Technical Documents: Why Bother?

Many professionals in the field of technical writing involved in the design of instruction guides, will at some point in their career have experienced some doubt whether their efforts to produce high quality documentation really make sense. Do consumers attach some value to the instruction guides for the products they have purchased? Do they use these documents at all, or are most instruction guides thrown away, together with the packing material of the equipment they come with?

Jansen, C. Indus (2002). Articles>Documentation>Usability

Determining the Right Training and Documentation Solution  

Frequently a product has documentation associated with it. Large products may have training and documentation. However, as corporations are 'rolling out' new technology to their staff they are becoming aware that supporting the user through a unified documentation and training strategy, results in fewer problems and faster integration and usage. This paper addresses the process of determining the right solution and an effective design and development process.

Rockley, Ann and Hifary Shirley. STC Proceedings (1997). Articles>Documentation

Determining When to Use Show-Me Helps and Demos  

The availability of powerful yet easy-to-use multimedia tools enables technical writers to consider a powerful new form of embedded user assistance: show-me help. This paper provides an overview of who is currently using show- me help--some current research, some history, and some definitions. It offers some guidance in choosing tools, designing show-me help, and deciding when to include then, concentrating on consideration of your users, potential topics, subsequent releases, and translation. It also suggests how show-me helps can be reused as part of product education and single-sourced into user assistance from the Web. When this information is presented in a conference session, the final part of that session will be a workshop in which a sample show me will be built using the QarbonTM ViewletBuilderTM tool. For this session, you have a choice to watch or do. You can watch as I create a show me for Windows(R) Explorer in this session or you can go to www.qarbon.com, download the demo version of ViewletBuilder, and do the exercises along with me.

Norris Bradford, Annette. STC Proceedings (2005). Articles>Documentation

Determining When to Use Show-Me Helps and Demos

The availability of powerful yet easy-to-use multimedia tools enables technical writers to consider a powerful new form of embedded user assistance: show-me help. This paper provides an overview of who is currently using show-me help--some current research, some history, and some definitions. It offers some guidance in choosing tools, designing show-me help, and deciding when to include then, concentrating on consideration of your users, potential topics, subsequent releases, and translation. It also suggests how show-me helps can be reused as part of product education and single-sourced into user assistance from the Web.

Bradford, Annette Norris. WritersUA (2005). Articles>Documentation>Multimedia>Video

Developing a Project Life Cycle for Technical Publications  

Having a technical publications project life cycle (pLC) that parallels an organization's product life cycle (PLC) greatly facilitates its adoption by engineering or development organizations. A technical publications project life cycle relates major documentation project management strategies, tasks, and deliverables to the same model used by technical organizations to control product development in an efficient and cost-effective manner. Some technical organizations perceive the documentation development process as being “intrusive” into the product development process, particularly during the Implementation Phase of the PLC. Communicating a technical publications pLC to these organizations early in the PLC eliminates this misperception.

Le Vie, Donald S., Jr. STC Proceedings (2003). Articles>Documentation>Project Management

Developing a Web-Based Tutorial in RoboHelp

The very first thing you should do in developing a tutorial is to be familiar enough with the subject matter that you can write the content.

School for Champions (2005). Articles>Documentation>Writing>Technical Writing

Developing Documentation for ISO 9000 Certification: Case Studies from the United States and Europe  

This panel discussion clarifies the implications of ISO 9000 certification for writers and editors and presents European and U.S. approaches to developing documentation for certification.

Carom, Barbara L., Mary Louise O'Connell and Wesley Chase. STC Proceedings (1993). Articles>Documentation>Case Studies>ISO 9000

Developing HTML Documents and Help System  

This document explains necessary tips for providing product information in digital form, giving specific examples of choosing the suitable media, classifying information, appropriate linking, file organization, etc. through our experience (in Fuji Xerox Co., Ltd.) during the development of the software product called Web PrintVision.

Ito, Sachi. STC Proceedings (1998). Articles>Documentation>Online>Help

Developing ISO 9000 Procedures  

Documentation is the foundation upon which an ISO-compliant quality system is built. Creating this documentation isn’t, however, as easy as it seems on the surface. Understanding the concept of the Standard enables writers to understand the content requirements. The structure this documentation follows will also impact the success of your registration audit. Once the documentation has been created, the control of it becomes of paramount importance. ISO requires that you control not only the documents and data you create, but also those that you receive from outside sources. Document and data control issues are one of the most common causes of registration failure!

Robinson, Ralph E. STC Proceedings (1996). Articles>Documentation>Policies and Procedures

Developing Knowledge Base Articles

A short article that offers some tips on writing articles for a knowledge base, whether internal or client facing.

DMN Communications (2008). Articles>Documentation>Writing>Technical Writing

Developing Online Help for OS/2 Applications  

One of the biggest problems facing Help developers is that of providing users with adequate methods of navigation through what can be huge amounts of information. After more than a two or three jumps, users can find themselves in topics that might be useful, but with no clear indication of how they got there or how to return to where they started. OS/2 gives the Help developer extraordinarily flexible tools for creating online documentation that can prevent this situation and provide users with a clearer path through online information than many other platforms can provide. However, this enhanced usability is not without its cost.

Radecki, Steven Lewis. STC Proceedings (1993). Articles>Documentation>Online>Help

Developing Online Help in Lotus Notes  

If you are a technical writer or manage technical writers and have been asked to document Lotus Notes applications, this workshop will give you a jump start. You can use the features available in Notes to create an effective help system as a Notes database. This help database can either be a view in an existing Notes application or a stand-alone database linked to the application. In this workshop, you will learn the basics of creating help systems in Lotus Notes.

Gross, Jacqui, Faye Smith and Steve Charles. STC Proceedings (1998). Articles>Documentation>Help>Online

Developing Troubleshooting Publications for Complex Systems: A Case Study: Troubleshooting Router-Based Internetworks  

The process of troubleshooting problems in complex systems involves systematically obtaining and synthesizing information from many sources, Creating troubleshooting support documents involves an analogous planning and development process. Three activities are essential to the creation of successful troubleshooting materials: cultivating strategic partners, designing an effective document, and implementing efficient information gathering processes. The unique nature of troubleshooting information requires approaches to these activities that can be adapted to different situations. This paper uses an informal case study format to illustrate how several techniques developed at Cisco Systems, Inc. can be used to create troubleshooting material for any complex system.

Lew, H. Kim. STC Proceedings (1994). Articles>Documentation

Developing WebHelp: What 'How to' Design Doesn't Always Tell Us  

Development of the Intranet application STAR.IDN for requesting and receiving medically related supplies illustrates a broad spectrum of technological and user issues. As such it serves as a case study of design and user-related decisions between an application designer and a Help author. Central to the study is the argument that design must be based on an empirically 'informed' rather than 'assumed' user model. The project also challenges Web literature that does not address user considerations in its promotion of design methods.

Eiler, Mary Ann and Kathleen Bright. STC Proceedings (1998). Articles>Documentation>Online>Help

Development of Japanese-Language CD-ROM Manuals Using SGML  

Fujitsu Limited publishes as many as 10,000 manuals a year. Efficient, standardized manual production is, therefore, indispensable. Our department has created a manual on CD - ROM as a pilot project of electronic publishing using the Standard Generalized Markup Language (SGML). The use of CD - ROM provides the manual with a convenient reformation search feature and high portability that can not be achieved with conventional paper manuals. This paper discusses our methodologies, problems involved in Japanese language SGML manual production, and how we solved them.

Nakamura, Yuko. STC Proceedings (1994). Articles>Documentation>Localization>Japan

Development, Use and Profitability of Translation Memory Systems

Product life spans and documentation production times are becoming increasingly short and the expenditures for documentation are rising simultaneously with increasing product complexity. Hence, translation projects are becoming more costly as the parallel increasing documentation complexity.

Knauf, Ansgar. TC-FORUM (1999). Articles>Documentation>Localization>Machine Translation

Distributing Cross-Platform, Cross-Browser HTML Help Using the Microsoft Java Applet  

In a previous article we discussed what browser-based HTML Help is, and how you can use the HTML Help ActiveX control to create and distribute web-based HTML Help to Microsoft Internet Explorer Users. In this article we'll explain how to use the Microsoft Java Applet to create and distribute Help systems that can be viewed by an Java-enabled browser.

ComponentOne (1999). Articles>Documentation>Online>Help

Distributing Web-based HTML Help

In this article we discuss what browser-based HTML Help is, the sitemap file that's behind the HTML Help table of contents, how the HTML Help ActiveX control HHCTRL.OCX interprets and displays this sitemap file, and how you can automatically distribute HHCTRL.OCX.

ComponentOne (1998). Articles>Documentation>Online>Help