The total quality assurance effort requires that programs be documented properly. Software, systems, and formal and informal procedures need to be documented so that systems can be maintained and improved. Documentation allows users, programmers, and analysts to “see” the system, its software, and procedures without having to interact with it.
Turnover of information service personnel has traditionally been high in comparison with other departments, so chances are that the people who conceived of and installed the original system will not be the same ones who maintain it. Consistent, well-updated documentation will shorten the number of hours required for new people to learn the system before performing maintenance.
There are many reasons why systems and programs are undocumented or underdocumented. Some of the problems reside with the systems and programs themselves, others with systems analysts and programmers.
Systems analysts may fail to document systems properly because they do not have the time or are not rewarded for time spent documenting. Some analysts do not document because they dread doing so or think it is not their real work. Furthermore, many analysts are reticent about documenting systems that are not their own, perhaps fearing reprisals if they include incorrect material about someone else’s system. Defenders of the SDLC approach remind us that documentation accomplished by means of a CASE tool during the analysis phases can address many of these problems.
Procedure Manuals
Procedure manuals are common organizational documents that most people have seen. They are the English-language component of documentation, although they may also contain program codes, flowcharts, and so on. Manuals are intended to communicate to those who use them. They may contain background comments, steps required to accomplish different transactions, instructions on how to recover from problems, and what to do next if something isn’t working (troubleshooting). Many manuals are now available online, with hypertext capability that facilitates use.
A straightforward, standardized approach to creating user support documentation is also desirable. To be useful, user documentation must be kept up to date. Use of the Web has revolutionized the speed with which assistance can be obtained by users. Many software developers have moved user support—complete with manuals, FAQ pages, online chat, and user communities—to the Web.
Key sections of a manual should include an introduction, how to use the software, what to do if things go wrong, a technical reference section, an index, and information on how to contact the manufacturer. The biggest complaints with procedure manuals are that (1) they are poorly organized, (2) it is hard to find needed information in them, (3) the specific case in question does not appear in the manual, and (4) the manual is not written in plain English.
