#20328
First Contact: Talking to Your Documentation Users 
You've never met them before. To you, they may represent the unknown and the strange. They view things differently, and their ways may seem almost alien. Yet you are supposed to serve their needs. They are your customers. Isn't it time you made first contact? In this paper, we share lessons learned and invite you to being your own voyage of discovery.
Macdonald, Kyla and Judith Rachel. STC Proceedings (1998). Articles>Documentation>User Centered Design
#31727
Customer support costs account for as much as 60 percent of a high-tech company’s total costs. Documentation is the first line of support for most customers, and customers usually use documentation to find the answer to a problem they’re having. The inevitable result of poor or nonexistent documentation is that more people try calling the customer support lines for help.
Butow, Eric. Software Development Times (2006). Articles>Documentation>Software>Technical Writing
#14256
For decades, journalists have used a proven approach called the 'Five W's' to answer the questions that the readers of newspaper articles most commonly want writers to answer. The questions are sufficiently useful that they can easily be applied outside newspaper writing, and I've already written about this in the context of audience analysis (Hart 1996). In this article, I'll show you how you can use these questions to develop more useful online help. Each of the five W's is a simple question that starts with the letter W: Why, Who, What, Where, and When. Some authorities add a sixth question, 'How,' to this list, but 'how to' information generally fits under what, where, or when, depending on the nature of the information. Users of online help can benefit greatly from the proven journalistic approach if we can answer these same five questions for each help topic that we create. In the remainder of this article, I'll provide an example of a failure to ask these questions, show how asking these five questions could have prevented this failure, and provide examples of typical questions we should be asking. Please note that, although I've presented these five questions in an order that seems logical to me, in practice the approach becomes iterative: It doesn't much matter where you begin, since answering one question often reveals important aspects of the other questions that you'd not yet considered.
Hart, Geoffrey J.S. TECHWR-L (2002). Articles>Documentation>Help
#28030
Flare 5: Adding Advanced HTMLHelp Features
Flare current provides the majority of HTMLHelp settings, and does this in a much more flexible way that HTMLHelp workshop does. Particularly useful are the WYSIWYG help window size and potitioning. However, there are some advanced HTMLHelp settings (such as advanced help, or remembering the users last help settings) that are not currently available.
Tech Write Tips (2006). Articles>Documentation>Software>Madcap Flare
#25207
FlashHelp: The Ideal Online Help Format for Web Applications
As the web transitions from a relatively static, information-oriented environment to a highly interactive, task-oriented environment, web developers must provide on-demand user assistance to ensure the usability of their applications.
Sibley, Jake. Adobe (2004). Articles>Documentation>Multimedia>Flash
#10812
Forget About the Lawyers! First, Let's Kill the Editors! Right?
Some companies and upper management, and even some documentation managers and writers, seem to agree. After all, in today's world of desktop publishing, writers are also typesetters and illustrators -- why not let them be editors as well? They know English. So why not save money, terminate the editors, and let peer editing begin? Or if we do keep some editors, let them be the designers, illustrators, and typesetters. As for language? Forget it! The readers will understand. Besides, who reads documentation anyway?
Sorotskin, Marilee J. Boston Broadside (1991). Articles>Editing>Documentation
#23321
From Afterthought to the Development Team
Honda of America's adoption of a structured analysis and design (SA&D) methodology for software development has allowed the Technical Publications Group to improve project planning. Documentation is now integrated into the system development methodology, and writers receive deliverables such as design documents and approved project plans earlier in the development process. With the addition of a project management tool that provides a central repository of project data, the group now creates more accurate preliminary and detailed documentation project plans. Results include an increase in documentation delivered at system implementation, and improved allocation of resources.
Hartsel, Joe A., Catherine S. White and Joanne R. Young. STC Proceedings (1994). Articles>Documentation
#23576
This presentation addresses designers and documenters who develop technologies for human use. The content is based on an intensive 42-hour training package, developed by Communications and Training Inc. Course content and duration can be modified to meet individual requirements. One day interactive workshops are also available.
Hofer, Klaus C. STC Proceedings (1994). Articles>Documentation>User Centered Design
#27922
From English to Cyrillic to Chinese
The increasing number of languages that companies need to translate into requires careful planning when preparing translation projects. Thus, choosing appropriate tools, finding qualified project teams, and applying suitable concepts to avoid additional work become crucial tasks for the project manager. If all these issues are considered beforehand, a perfect balance can be achieved within the magic triangle of time, cost and quality.
Kreitmeier, Peter. tekom (2006). Articles>Documentation>Localization
#21026
From Good to Great—: The Finer Points of Writing User Documentation
A few years ago, the NeXT user publications group was handed a charter to create casual books with personality. We were also told to condense the user documentation for an entire operating system and several bundled applications into 300 pages. And of course we had the top priority of creating accurate, complete, and easy-to-use documentation. To our delight, these goals ended up being mutually compatible. The keys? Task orientation, flat hierarchy, carefully crafted page design, illustration, and a casual, intelligent tone. We also broke some 'rules'! (Caution: Some of the following material may seem radical to seasoned traditionalists.)
Casabona, Helen. STC Proceedings (1995). Articles>Documentation>Software>Usability
#20341
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
#21510
From Online Document to Electronic Performance Support System
This demonstration introduces the concept of an Electronic Performance Support System (EPSS), an online end-user support system that provides whatever is necessary to generate performance and learning at the moment of need. The speaker will step through a five-level analysis of the design and delivery components of an EPSS and demonstrate how to design and position online documents for inclusion in an EPSS.
Hyman, Francine N. STC Proceedings (1994). Articles>Documentation>EPSS>Online
#23661
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
#23597
A panel of industry experts provides an overview of the CD-ROM publishing process—and its business issues–for technical communicators who are responsible for implementing CD-ROM publishing in their organizations. The panelists will discuss how to gain the benefits of reduced manufacturing warehousing and distribution costs, without degrading documentation quality.
Gale, John, Stephanie L. Rosenbaum and Pamela Sansbury. STC Proceedings (1994). Articles>Documentation>Online
#20330
From Purchase to Productivity: Bridging the Documentation Gap
This presentation will describe an area of documentation that is often overlooked--that which covers the process between the customer purchasing a computer system or upgraded software and the customer becoming productive using that system or software. This information includes all that needs to be planned and accomplished to get new software up, running, and integrated with existing software. Unisys Corporation fills this gap with what we call 'Release Documentation.' This presentation describes the who, what, where, when, and how of that process.
Alexander, Bruce, Avis French and Elaine Randolph. STC Proceedings (1998). Articles>Documentation>User Centered Design
#28370
From Software Documentation to E-learning: Making a Switch
Interested in making the transition from software documentation to e-learning? Read about some steps that will help you ease the switch and make the most of your new opportunity.
Malhotra, Dhupinder K. Intercom (2006). Articles>Documentation>Instructional Design
#30275
From Technical Writing To Science Communication: How Do We Make The Leap?
In response to their institution's need to explain its research to the public, a group of technical writers from Los Alamos National Laboratory is investigating methods to help writers make the leap from technical writing to science communication--the art of communicating science to nontechnical audiences. Through individual study and networking, members of the group are collecting resources that illuminate the techniques and complexities of science communication. From this foundation, they are preparing an extensive, annotated bibliography and assembling training materials so that they can become a resource for other writers shifting from technical to science communication.
Agnew, Marion, Anne Garnett, Grace Hollen, Amy Longshore, Judy Machen, Ann Mauzy, Eileen Patterson and Amy Reeves. STC Proceedings (1994). Articles>Scientific Communication>Documentation
#19057
Technical communicators have become increasingly interested in how to 'open up' the documentation process - to encourage workers to participate in developing documentation that closely fits their needs. This goal has led technical communicators to engage in usability testing, user-centered design approaches, and, more recently, open source documentation. Although these approaches have all had some success, there are other ways to encourage the participatory citizenship that is implied in these approaches. One way is through an open systems approach in which workers can consensually modify a given system and add their own contributions to the system.
Spinuzzi, Clay. ACM SIGDOC (2002). Articles>Documentation>Information Design>Open Source
#27646
The RoboHelp help authoring tool is now entering its thirteenth year of existence. That's a remarkably long existence for any software title. In that time period, we have seen an amazing expansion of the software industry throughout the 1990s and an equally amazing retraction due to the bursting of the Internet bubble. Making its start in the tiny offices of Blue Sky Software in LaJolla, California, RoboHelp grew into an extremely profitable product. It is also a market leader—having capturing some two-thirds of all Help authoring tool sales. During the Internet bubble years the company changed its name to eHelp, but RoboHelp continued to be its flagship profit center. In 2003, eHelp (and RoboHelp) were acquired by one of the leading providers of web tools—Macromedia. Now it appears that the end may be approaching for RoboHelp.
Welinske, Joe. WritersUA (2005). Articles>Documentation>Software>Adobe RoboHelp
#18810
The Future of the User's Guide in the Documentation Set
With online help rapidly becoming the central piece in the documentation set, software companies might consider two different directions in their documentation planning. The first is to think of the user’s guide as a high-quality supplement to help. The second is to think of the user's guide as a transitional piece that will adequately support users while they make the transition to a largely online documentation set. Each of these directions carries different implications for the design of the user’s guide.
Farkas, David K. STC Proceedings (1994). Articles>Documentation
#22904
Genre Ecologies: An Open-System Approach to Understanding and Constructing Documentation 
Arguing that current approaches to understanding and constructing computer documentation are based on the flawed assumption that documentation works as a closed system, the authors present an alternative way of thinking about the texts that make computer technologies usable for people. Using two historical case studies, the authors describe how a genre ecologies framework provides new insights into the complex ways that people use texts to make sense of computer technologies. The framework is designed to help researchers and documentors account for contingency, decentralization, and stability in the multiple texts the people use while working with computers. The authors conclude by proposing three heuristic tools to support the work of technical communicators engaged in developing documentation today: exploratory questions, genre ecology diagrams, and organic engineering.
Spinuzzi, Clay and Mark Zachry. Journal of Computer Documentation (2000). Articles>Documentation>Rhetoric
#26197
A tutorial on writing documentation that will be used in a particular project.
Galassi, Mark. Galassi.org (1998). Articles>Documentation>Standards>DocBook
#24249
Getting a Count: Recording Metrics in Documentation Plans
Most large documentation departments are already using some kind of a formal documentation project planning strategy. Many are modeled after the work of Dr. JoAnn Hackos, with information plans, content specifications, and/or documentation plans (Hackos, 1994) 1 . By carefully adjusting the look and feel of the planning documents, adding room for recording actual numbers at the completion of the project, managers can implement a metrics strategy that takes advantage of existing templates and piggy-backs on existing archiving and checkout procedures.
Romaine, Garret H. STC Proceedings (1999). Articles>Documentation>Project Management
#25444
This chapter is intended to provide a quick introduction to structured markup (SGML and XML). If you're already familiar with SGML or XML, you only need to skim this chapter. To work with DocBook, you need to understand a few basic concepts of structured editing in general, and DocBook, in particular. That's covered here. You also need some concrete experience with the way a DocBook document is structured.
Walsh, Norman and Leonard Muellner. O'Reilly and Associates (1999). Articles>Documentation>Standards>XML
#27740
Getting Started with the DocBook XML Dialect
Gets you started with DocBook, an SGML/XML dialect that describes the content of technical articles and other documents. David discusses the benefits of using DocBook, and then describes how to plan and modularize a large document conversion project.
Mertz, David. IBM (2000). Articles>Documentation>XML>DocBook
