Cover Image
close this book Food Composition Data: A User's Perspective (1987)
close this folder Other considerations
close this folder Systems considerations in the design of INFOODS
View the document (introductory text)
View the document Introduction
View the document Staff turnover and system growth
View the document Documentation
View the document The choice of environmental and basic tools
View the document Choices of operating systems
View the document Choice of programming language
View the document User interface
View the document Data representations
View the document System architecture and linkages
View the document Stability
View the document Primitive tool-based systems
View the document Summary
View the document References

Documentation

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.