Case Study: Reaching New Markets Through Clear Documentation

Triangle is a systems integrator in the UK with about 150 employees. It extended the functionality of the InfoGenesis point of sale software onto hand-held terminals. To turn this into a commercial off-the-shelf product, Triangle needed clear documentation for resellers and for staff managers at customer sites. Triangle lacked the expertise needed to produce effective documentation, so it outsourced the documentation development. The new documentation enables Triangle to roll out the software internationally using resellers, and keeps Triangle's support costs to a minimum.

Unwalla, Mike. TechScribe (2008). Articles>Documentation>Case Studies

Cataloging Information Aids Help Development

Context-sensitive help systems often need redundant placement of information. This ensures that the information is seen by visitors who enter and move unpredictably through the system. Redundant placements take the form of descriptions, explanations, warnings, and the like that amplify other subjects. In software documentation, for example, some candidate subjects include the purposes of screens and tabs, the effects of selected options and significant functions such as Delete, and reminders of required access permissions and prerequisite steps or conditions. You can save development time and promote consistency by cataloging information so that it can be inserted wherever needed using your authoring software's copy and paste functions.

Barten, Alfred. Boston Broadside (2001). Articles>Documentation>Indexing

Caution--Warning Ahead!  

Safety and warning notices form the most important elements of user information wherever safety and [product liability are concerned. A carefully thought out and systematic process is required in developing safety-relevant information, in order to increase the completeness and comprehensibility of product safety. This will also disarm any suspicion of gross negligence in internal documentation in case of missing safety notices and it will ensure traceability.

Schmeling, Roland. tekom (2006). Articles>Documentation>Risk Communication

CD-ROM: From Print to Prototype  

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 John Gale 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.

Rosenbaum, Stephanie L., John Gale and Pamela Sansbury. STC Proceedings (1993). Articles>Documentation>CD ROM>Online

CD-ROM: From Print to Prototype  

There are many significant benefits to releasing documentation on CD ROM rather than on hardcopy including cost savings, storage capacity, and the ability to implement search and retrieval functionality. To determine whether or not you should go to CD ROM, it is advisable to survey your users and to get approval from the folks in "corporate." Once you decide to pursue CD ROM, you need to determine the platform requirements and feature set of the search and retrieval software. You will then be able to choose from a variety of products, and ask the selected vendor to produce a prototype for you.

Florsheim, Stewart J. STC Proceedings (1993). Articles>Documentation>CD ROM>Online

Challenges and Advantages of Modular Documentation  

Using a modular process has proven highly effective in developing both on-line and printed documentation. This paper identifies module types and structures, discusses technical, psychological, and management hurdles, and demonstrates how this process can improve consistency and quality. In addition it discusses tools and resources, preliminary planning, preparation of personnel, and (briefly) tracking results.

Greene, Linda L. STC Proceedings (2000). Articles>Documentation>Single Sourcing

The Challenges of Open-Source Documentation and Training

There are at least two important issues that are closely related to the open-source software support questions we raised in part 1 of this look at open-source practicalities: documenting the software and training people to use it. With a traditional, commercially licensed product, documentation is as simple as obtaining a hard copy, a CD or going online to get all the details needed from the software's developer. Or, if something is missing, using support from the vendor to get questions and issues resolved.

Smith, Tom. Open Enterprise, The (2003). Articles>Documentation>Open Source

Challenging Old Key Factor Assumptions to Revamp Documentation Strategy  

The Information Products (IP) group at Sun Microsystems Computer Company (SMCC) recently revamped thew documentation strategy for computer server products. While creating the new model, we realized that our goal for more streamlined documentation would be more attainable if we did not restrict ourselves. Instead of starting with an old, key factor assumption — that manuals should be written with 'Who is the customer?' in mind — we addressed questions such as 'What tasks are required during installation and maintenance?' and 'Who perform these tasks?' By replacing some old ideas with fresh ones, we developed a new documentation strategy.

Daniels-Ball, Denise. STC Proceedings (1996). Articles>Documentation>Case Studies

Cheating the Quality Triangle  

Hart discusses ways that technical communicators can simultaneously improve the quality of their documentation, increase the speed with which it is produced, and lessen the costs of producing it.

Hart, Geoffrey J.S. Intercom (2001). Articles>Documentation>Quality

Checkliste zur Qualitätssicherung Technischer Dokumentation

Einfache Checkliste zur Beurteilung und Verbesserung der Qualität Technischer Dokumentation, insbes. Technischer Dokumentation für Software (Software-Dokumentation) wie Handbücher, Online-Hilfen sowie interaktiver Demos und Tutorials.

Achtelig, Marc. indoition engineering (2006). (German) Articles>Documentation>Quality>Documentation

Cherryleaf Survey: Uptake of New Help Trends

During March and April 2003, Cherryleaf carried out an online survey into the current trends in technical communication. One of the questions we asked was: Do the online user assistance documents produced by your organization contain the following advanced capabilities?

Cherryleaf (2003). Articles>Documentation>Help>Online

Choices, Challenges, and Constraints: Documentation and Newsletters Over the World Wide Web  

Providing timely information to diverse users on different platforms can challenge any document delivery system; however, the World Wide Web provides an effective solution for some applications. While the Web presents some extra problems and challenges that other media do not, the results justify the resources required. This paper describes and evaluates an implementation of Computing and Information Services documentation on the World Wide Web.

Ray, Eric J. STC Proceedings (1995). Articles>Documentation>Online

Choosing and Using Help Topics

This paper describes some common types of help topic and when to use each. Different applications require different mixes of help topics. Choose the topic types that are appropriate for the application you are documenting.

Hollis Weber, Jean. Technical Editors Eyrie (1999). Articles>Documentation>Online>Help

Combining Usability Research with Documentation Development for Improved User Support  

Describes two case studies where Tec-Ed leveraged usability research and documentation activities to create solutions that met the needs of both our clients and their customers.

Keirnan, Timothy, Lori Anscheutz and Stephanie L. Rosenbaum. Tec-Ed, Inc. (2002). Articles>Documentation>Usability

Review: Commentary on: "Little Machines: Understanding Users Understanding Interfaces"    

Online materials, as Johnson-Eilola points out, too often provide speed but neither learning nor conceptual information. Minimum information is often provided in help systems because there are no resources to provide more. But the result is often a system that, without any conceptual information, provides little more than help that is so obvious that it ceases to be helpful. Even when resources are constrained, help systems should, at a minimum, refer to external sources that can help users with important concepts behind the tasks they are trying to perform.

Haramundanis, Kathy. Journal of Computer Documentation (2002). Articles>Reviews>Documentation

Communicating Rapidly Changing Information  

When purchasing complex software products, users frequently receive large quantities of information; however, to use the product efficiently, they need a visually obvious starting point that helps them locate the specific information they need. With maintained With the quantity and diversity of information, customers need to be able to find the information they need without flipping through endless pages. In order to give the users a starting point in all of the printed and ASCII file information. we created a document entitled the Guide to products, users can use the features available with a new release most efficiently if they have an overview of the major changes to the product and to the information about the product. By using visual devices and creating an overview document. for each release, technical communicators can decrease their costs and increase users' productivity.

Bown, Jennifer and Connie M. Bibus. STC Proceedings (1993). Articles>Documentation>User Centered Design

Compaq QuickFind: The Editorial Process from Print to CD-ROM  

COMPAQ QuickFind is a CD-ROM database of COMPAQ product information. Available by subscription, QuickFind offers full-text search-and-retrieval functions and full-color graphics in a 350-megabyte database. QuickFind incorporates hard-copy information into an electronic format. The QuickFind editorial process (converting hard- copy information to searchable files) is the key to creating a valuable, centralized support tool for COMPAQ dealers, customers, and internal personnel.

Tacker, Susan and Susan L. Maloney. STC Proceedings (1993). Articles>Documentation>CD ROM>Online

Comparative User-Focused Evaluation of User Guides: A Case Study    

A comparative evaluation of two user guides,--the document traditionally used by a company and a model document designed on the basis of research results and recommendations,--was carried out using a number of complementary approaches focusing on the user. The quality and suitability of these documents for the target audience were assessed in terms of content, structure, presence of certain organizational devices (such as headings) and pictures included. The results revealed that the model document was more attractive, more efficient, and better adapted to users' needs, thanks to its modular organization (being structured according to "functions"), a large number of pictures, the presence of headings, and rationalization of the vocabulary used.

Ganier, Franck. Journal of Technical Writing and Communication (2007). Articles>Documentation>Assessment>User Centered Design

Comparison of HTML Produced by Several Help Authoring Tools (HATs)

Recently, there was a lively discussion on the Help Authoring Tools and Techniques (HATT) mailing list about the relative compactness and efficiency of the HTML code produced by various Help authoring tools. As a result of these discussions, several industry consultants decided to collaborate on a project to compare the HTML, CSS, and CHM files produced by a variety of Help authoring tools.

Knopf Online. Articles>Documentation>Online>Help

Comparison of Online Help Formats

This article lists the basic differences between WinHelp version 4, Microsoft compiled HTML help, WebHelp and pure HTML help. Samples are available.

Unwalla, Mike. TechScribe (2003). Articles>Documentation>Standards>Help

A Comparison of Two Evaluation Techniques for Technical Documentation

This study compared two evaluation techniques, Usability Testing and Cognitive Walkthrough, in their ability to identify errors in aviation maintenance documentation. The techniques were evaluated to see how much unique information they each produced as well as the type of errors identified. Results showed that the techniques were complementary in their findings and both are recommended in the development of technical documentation.

Rogers, Bonnie Lida, Chris Hamblin and Alex Chaparro. Usability News (2005). Articles>Documentation>Assessment>Usability

Complex Technology Calls for Intelligible Documentation  

By means of the tekom guidelines (check list) the technical author can particularly check the documentation of a product. However it is not the product which can be checked by means of this check list, but only the product’s documentation.

Noack, Claus. STC Proceedings (1996). Articles>Documentation>Technology

Constructing a One-Stop "Answer Station" for Software Users  

The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete "Answer Station" that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This paper discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.

Bleiel, Nicoletta A. and Beth A. Williams. STC Proceedings (2004). Articles>Documentation>Help>Online

Constructing a One-Stop "Answer Station" Website for Software Users

The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete 'Answer Station' that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This article discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.

Bleiel, Nicoletta A. and Beth A. Williams. WritersUA (2004). Articles>Documentation>Web Design>Help

Constructing Usable Documentation: A Study of Communicative Practices and the Early Uses of Mainframe Computing in Industry    

This study suggests that documentation is a complex technical communication genre, encompassing all the texts that mediate between complex human activities and computer processes. Drawing on a historical study, it demonstrates that the varied forms given to documentation have a long history, extending back at least to the early days of commercial mainframe computing. The data suggest that (1) early forms of documentation were borrowed from existing genres, and (2) official and unofficial documentation existed concurrently, despite efforts to consolidate these divergent texts. The study thus provides a glimpse into the early experimental nature of documentation as writers struggled to find a meaningful way to communicate information about their organization s developing computer technology.

Zachry, Mark. Journal of Technical Writing and Communication (2001). Articles>Documentation>History