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.
|
