Software documentation standards have risen steadily over the past several years, and this trend is likely to continue. Just as the personal computer revolutionised computing by turning it into a mass market commodity, mass market computing is making it necessary to improve accessibility, formatting, and readability of documentation. Gone forever are the days when a binder of typed specifications from the engineering staff sufficed for program information. Today, details of program operation must be easy to find, easy to read, and preferably, available from within the program itself. This makes creation of a well organised documentation system essential.
Just as software has progressed from program to application, it is important to view today's documentation not as a user manual, but as a system. The system may be composed of several different types of modules using different media. The important thing is that it must provide accurate information in accessible form at the point where it is needed. Both audience and information requirements will vary radically for each component. Thus, it would be as inappropriate to provide marketing copy in a Help system as it would be to provide a low level technical description in a marketing brochure.
Development of a strong documentation system requires an integrated plan that includes all printed and online elements. In many cases, some degree of replication between the paper and online forms is desirable; this relationship needs to be mapped out so that material can be updated. The online documents and print documents should reinforce each other, with at least something of the same look and feel behind them.
Creation of documentation systems requires an increasing number of skills, some of which may not be readily available. First, the information needs to be created and written by a competent technical writer. Technical writing requires special skills, and should not be undertaken by the project engineer or secretarial pool. The writer needs to have literary and technical experience, plus special training.
While the information is being created, graphics need to be developed for both online and print versions. Note that the graphics and formatting requirements of printed and online documents can be very different. While the printed version needs layout and desktop publishing skills to create a final version, the online document may require significant coding. These coding requirements are growing in complexity and in importance as online documents move to include multiple windows, sophisticated search capabilities, and even animations.
As documentation systems become more sophisticated and better adapted to the work environment, user expectations are also being raised. The "old guard" analyst's idea that user guides exist only as an irritating necessity is being challenged on all fronts; particularly as the documentation system begins to merge with the program in the form of tutorials and "Wizards."
To achieve an effective result, technical communicators need to be involved with the product at a much earlier date than previously, because the documentation system is now a significant part of the user interface and coding. A closer collaboration is also required, since portions of the online information may be heavily programmed and linked to the program code itself--as in the case of Wizards, demos, and context-sensitive help systems. The documentation system needs to be described at an early stage of product planning so that all of the pieces can be created and integrated when the project is completed. The technical needs of the documentation system also need to be addressed earlier, since some of the coding can be completed before the product is sufficiently developed for first draft documentation to be written.
For many software companies, the increasing sophistication of documentation requirements will require use of contract employees or external documentation companies. This trend is only beginning to appear in New Zealand; elsewhere, more than half of the technical writing profession is employed in contract or agency situations. This is an important development as the skill set required to create documentation systems continues to expand.
As these trends continue to develop in technical communications, markets are becoming increasingly internationalised, and global communications are developing in power and in sophistication. For New Zealand software developers, the requirement is to keep up with the play--and that means careful attention to the documentation system.
Copyright © 1996, Brian J. Dooley