Main BASIS Page
Main Advantage Page
This Issue's Table of Contents
BASIS Takes New Approach With Documentation Previous Article Table of Contents Next Article

By Paul Hughes

Suppose that you are on your way to a long-term assignment in a foreign country. You were given only twenty-four-hours notice before leaving, so you had little chance to learn about the local language, culture, and customs. Despite the immersion in an exotic environment, your company expects you to be productive within a week. If you were an old pro at such assignments, you might only need a list of banks, apartment houses, utility companies, and government agencies. If this was your first such assignment, however, you would probably also need step-by-step directions for performing nearly every task. Regardless of your level of experience, you would need accurate, well-organized, and easy-to-read information to help steer you through the obstacles ahead.

Software developers are often called on to take "foreign assignments." Getting up to speed with a new application, particularly in an industry with such rapidly changing technology, can be a challenge. With this in mind, BASIS seeks to provide software documentation that enables developers to quickly create, maintain, upgrade, and troubleshoot their applications. Thus, BASIS is revamping not only its manuals but also the approach to their creation and revision. The most important elements of the new approach are creating a task-oriented structure, improving readability, and providing multiple document formats for distribution.

First, BASIS is implementing a task-oriented structure that focuses on informing users based on what they need to do and then explaining how to do it. It is not organized around a product's functional structure (screens, menus, etc.), but rather around a goal the customer has in using the product. At BASIS, task-oriented documentation starts with an analysis of what users want to accomplish, then works backward to find the procedures and inputs necessary for doing the job. The value of quality task-oriented documentation is evident to anyone who has tried to program a piece of consumer electronics equipment. Although many such products are well-documented, others have forced many of us to declare, "Describing the functions of the Mode button is not enough, tell me how to videotape my favorite show so I can watch it tomorrow night."

Second, BASIS is also implementing readability improvements that focus on helping users locate and process information as fast as possible. Effective headings allow customers to look at the table of contents and section introductions to get a high-level synopsis of what the document covers. Section introductions describe what's covered and itemize all necessary inputs: equipment, resources, and privileges. Graphics clarify concepts, processes, relationships, and equipment connections. A good installation procedures diagram can provide the same understanding as three or four paragraphs of text. Readability is especially important to BBx® customers for whom English is not the primary language. Standardized, succinct sentences reduce wordiness and ambiguity: "Turn on the monitor" is much easier to understand than "it is required that you turn on the monitor."

Third, BASIS is moving toward delivering documentation in both paper and online formats, which allows customers to receive product information in the format that best suits their needs. Because BASIS products run on many different platforms, providing online documentation that can be accessed by any system that contains a web browser is a logical alternative to hardcopy manuals. At TechCon97, BASIS unveiled an HTML version of preliminary Kilauea documentation. We plan to provide much more of this kind of online documentation in the future, eventually including interactive tutorials for new products.

Previous Article Table of Contents Next Article
Copyright 1999, BASIS International Ltd. All rights reserved.
Terms of Use