8.2.4 Documentation



Complete and comprehensive documentation is necessary when an existing model from elsewhere is being transferred and perhaps modified. Even at the "home" for the model, the original builder and/or computer programmer will eventually leave the agency. Therefore, documentation is required for ongoing use, for various users whose identities probably change over time, and for updating to reflect changing city characteristics or agency policies. A recent HUD-supported urban modeling effort at the Rand Corporation specified what we believe to be very reasonable documentation requirements for a transferable model [CHAI 78]:
1. An executive summary, containing a nontechnical introduction to the model, information to assist an administrator in deciding whether to use the model, and details about how the computer program can be obtained.
2. A technical description, to provide analysts with an understanding of the theoretical underpinnings of the model.
3. A user's manual, describing, step by step, how the model is operated once it is installed on a computer system.
4. A description of the computer program (a "programmer's manual"), written for data-processing personnel and providing sufficient information to permit installation of the model, construction of the required data base, and modification of the model, if desired.
Of course, simple models developed solely for local use may not require such extensive documentation.

Computer-related issues. Most models today are computer-implemented. This raises issues with regard to the following:
1. A model's computer requirements, including computer language (e.g., FORTRAN, COBOL, ALGOL, PL/1, SIMSCRIPT, etc.), core storage requirements, and execution-time requirements.
2. The computer capabilities available to the agency, including those of the city, local universities, and commercial vendors, as well as those controlled internally.
3. The computer experience of the user.
Many communities initiated computer usage several years ago, primarily for accounting purposes. A popular computer language for accounting is COBOL, which is implemented much more widely in municipalities than, say, PL/1 or even FORTRAN. Most models, however, are developed using a "scientific language," such as FORTRAN, PL/l, or ALGOL. Thus, the potential for a mismatch is apparent. Also, local computers often have severe core storage limitations. However, with the wide accessibility of commercial time-sharing computer services, the limitations of local computers should become less of a constraint in the future. For example, the PCAM program (Patrol Car Allocation Model), which was an outgrowth of two of the mini cases reported earlier, is supported on a commercial time-sharing system [CHAI 78].

A lack of computer experience on the part of the user may imply that more time and effort is necessary to "conquer the learning curve" of the model, as discussed in Section 8.3.