management

about Software Documentation

BY PAWAN NAYAR hese days, people are more aware of the importance of quality software documentation. Nonetheless, poor documentation persists. Why? In this article, Ive listed ten misconceptions about software documentation that may have contributed to this situation. I arrived at this list based on my experience as an instructional designer, technical writer, and technical editor. I believe that, if technical communicators and their managers are aware of these misconceptions, we can begin to address them in our workplaces. Eventually, we can create environments in which good documentation will flourish.

1. Software documentation is a support task.

This classic statement is probably based on the belief that software represents the code and only the code. As a consequence, the quality of software is seen as independent of the quality of its documentation. The idea of software documentation as a support task affects the quality of software documentation and has an impact on the end users. From the users perspective, the documentation, along with the user interface, is the most important part of the software. Users learn to use the software from its documentation. Any mistakes in documentation may result, therefore, in failure of the product: decreased sales, or at the least more support calls. It is important that the whole software industry understand that software documentation is just as important as code development and testing.
John Bleck/Laughing Stock

documentation 2. Software writing everything involves about the product.

While documenting everything about the product is an admirable goal, it is not always achievable. The goal in reality is to make software documentation instructional, as practical and simple as possible, and easy to use and recall. It is important to realize that the user does not have the time or patience to read reams of information. To improve software docu-

May 2000

27

management

The way technical communicators can help the industry change is by being more useful, more productive, and more assertive.

mentation quality, we should spend time on making topics consistent and easy to navigate. The content should be appropriate and well organized. Various checks (for example, reviews by the development team, in-house subject matter experts [SMEs], and end users) should be incorporated into the software development life cycle (DLC). Its time we shift the focus of software documentation from quantity to quality.

cialists. These people are trained to optimize a product and its documentation from the users perspective. Another way to improve documentation is to make the complete documentation set available to users during alpha and beta reviews. The users provide the most valuable feedback for improving the overall quality of software documentation; therefore, this procedure is vital.

3. If abecompromise has to made, software

documentation can wait.
This is an odd assumption arising from the belief that users will ignore gaps in documentation provided they get innovative product features. At times this assumption results in exclusion of important content and at other times in an improper level of detail and haphazard or confusing coverage of content. We need to allocate proper time for documentation needs. We should treat documentation as an integral part of software development and ship no software without covering its important features, capabilities, and limitations. Usage examples, tips, shortcuts, error/warning messages, troubleshooting guidelines, and so on should be part of each and every piece of software documentation.

5. The functional be specification can

updated late in the DLC.
The need to change or improvise product because of market conditions is a harsh reality. At times, features are changed even in late beta testing phase. Most technical writers agree that it requires three to six weeks after the final code release to perform mechanical and consistency checks (conformance tests) on documentation. These checks ensure a consistent look and feel in documentation and consistent writing style and depth in individual topics. Further, these checks ensure that documentation reflects the updated functional specification. Software documentation will suffer if the functional specification is not continually updated: consistency checks might fail and contradictory information might reach end users. Technical writers should always have enough time to do conformance tests. These conformance tests can begin only after the functional specification is updated.

4. Software developers and testing specialists can

perform quality checks on software documentation.
Software developers and testing specialist can provide the best feedback on technical accuracy and depth of product content. However, they may fall short on recognizing the proper explanation of concepts such as the rationale behind features or the reasons for doing tasks. To ensure the quality of software documentation, it is important for management to hire technical editors, instructional reviewers, SMEs, and usability spe-

6. Software documentation for different products

can follow different (read arbitrary or most appealing) styles.
There is a tendency to assume that different types of software documentation (help file, user guide, reference manual, Web documentation, customer support information, etc.) can follow different styles. While docu-

28

May 2000

management

mentation varies because of the complexity of the products subject, user profile, and user requirements, it is important to ensure that the style at the macro level of writing any software documentation is uniform, and is based on a style guide and a complete set of well-defined standards. Quality software documentation must reflect the culture of the firm and not the ability of individual technical writers. It would be unfortunate if some parts of the documentation were excellent because a creative senior technical writer wrote them, while other parts were perfect samples of improper documentation, produced by an inexperienced new hire. To ensure quality documentation, we must include checks and balances and set operations (quality reviews and spot-checks during each phase of the DLC) in such a way that, by the end of the project, the documentation has but one face.

8. Technical writing is neither creative nor

particularly difficult.
It is important for management to realize that technical writing is a taxing profession. Ideally, the technical writer should be both an expert in the product and a communication expert. These are rare talents: neither education nor organization alone can train or groom such people. While institutional mechanisms can work as catalysts, the technical writers themselves have to find the energy to develop an understanding of the product. At the same time, they have to develop a writing style that is clear and utilitarian. Proper investments in developing technical acumen and maintaining communication skills will ensure that technical writers continue to find their profession challenging and rewarding. Invariably, this will improve the quality of software documentation.

10. It is impossible to change.

The way technical communicators can help the industry change is by being more useful, more productive, and more assertive. Organizations are beginning to realize the cost advantage and revenue potential of software documentation. (Increasingly, software documentation is going the training route, where the focus is on getting a set of tasks done in the easiest, fastest, and most useful way.) With the future of the whole software industry resting essentially on the Web, documentation and spin-offs from documentation will become increasingly important. To participate in such a future, technical writers must play a greater role. The beginning lies in encouraging the users to identify their needs. Quality software documentation will automatically follow. In summary, the present state of software documentation is a result of both historical factors and day-to-day decisions. The continued misconception that software documentation is a support task that is essentially noncreative and a necessary evil for software sales has led to poor software documentation. The necessary commitment to improve the quality of software documentation is lacking both from management and software documentation professionals. On a more positive note, however, we live in the most interesting of times: Software documentation is becoming simpler, more useful, and more responsive to user needs.

7. Mergers/acquisitions
do not affect software documentation as much as code change.
In a time when most software firms are growing through mergers or acquisition, this idea is unfortunate. When they merge, firms place greater stress on integrating their product lines in terms of code and integrating workers in terms of culture. What is generally forgotten is the technical publications (or user education) department. The two merging firms may also be following different set of standards and may have different quality orientations, which may affect the quality of software documentation. At the time of the merger, management has to plan in sufficient detail how to merge the respective technical publications departments. All technical publication employees (or at least their representatives) must participate in creating a common style guide. This guide should be used to update all future product lines, and, if possible, all current product lines as well.

9. The userwritten. will understand what is

This is a classic belief propagated to shield incompetence or to justify incomplete documentation. If users are satisfied with what is poorly written, then they must believe there is no other recourse, or they must be in a position to understand the software without using its documentation. Technical writing is not about placing notes or compiling information, but about helping users to understand the conceptual framework of a problem and enabling them to complete tasks by themselves. The key words in documentation are not providing information, but enabling understanding and facilitating training. To train the user, the documentation should be organized for optimum usage. This demands structured content, which begins from a known framework and then expands to new terms and concepts, analyzing suitable examples, describing unique situations and limitations, and mixing graphics, sound, and animation to maximum effect.

Pawan Nayar is currently working as a technical writer at Cadence Design Systems in Noida, India. He is involved in writing for new and current products and in content editing the work of other writers. He is a trained instructional designer and instructional design reviewer. Pawan has frequent articles published in Express Computers, Computer Today, and in the Cyber India Online Limited Web site (www.ciol.com).

May 2000

29