Documentation standards

10.6 Documentation standards

A wide variety of documentation standards is available. In many companies and organizations, the first thing that is standardized is documentation. This may be because documentation is the least favorite activity of most software developers. It is the only product produced by a large portion of the SLC and is usually the object of most of the complaints about a system. Or perhaps it is the easiest to standardize since there are so many standard examples from which to choose.

Industry organizations have published or are developing standards for documentation, not only in the software field but also, and for a longer time, in the hardware arena. For example, the IEEE has standards for several software development documents (Table 2.1). These standards represent the consensus of a large portion of the computing industry. The Department of Defense and various other government agencies, such as NIST, have promulgated documentation standards both for general applications and for use in particular situations or special computing environments.

In some cases, these externally prepared standards can be used directly. Otherwise, they can be modified to fit the needs of an individual organization. These standards often include very specific content and format instructions so that very little is left to the author except the information to be documented. Others provide generic requirements or guidelines on which an organization can build. Some companies are willing to share their documentation standards or at least give guidance in the area.

As in the case of standards in general (see Section 2.2), each company or organization must develop or adapt documentation standards to meet its own specific needs. Documentation standards, like anything else, must serve the users of those standards or they will be improperly followed or ignored all together. It is incumbent on the software quality practitioner to review documentation standards periodically to be sure that they are up-to-date and appropriate for the organization. When they become inadequate or obsolete, the practitioner should prompt the standards coordinator to take action to improve them.