Documentation

The question of how to document a large system is a key one that should be addressed early and as part of the planning of the code and user interfaces. One approach is to provide comprehensive documentation; but comprehensive documentation may run into thousands of pages as the system grows [17]. Such volume will almost certainly lead to complaints about size and bulk, comments about needing wagons rather than binders, and requests that everything be distilled onto cards than can be put into pockets and purses. Standards about information to be included in documentation - algorithms [7,12,16], error messages, and the like, as well as sampling information and methods of analyses - make such volume inevitable; a mere four pages of description on each of 500 commands leads to 2,000 pages of documentation. On the other hand, documenting a large system as if it were a small one, adopting pocket cards or brief on-line files as the only form of documentation, or in some other way trying to keep the total under 100 pages will cause user frustration or worse. These are questions that do not have clear answers, but making choices early and clearly and remembering the reasons for the decisions that are made can help. At the same time, these decisions, like others discussed throughout this paper, should be made in a way that minimizes the damage if the world appears differently at some time in the future.