Sometime in the late 1960s or early 1970s the US government decided to replace its IBM computers with those manufactured by Honeywell. The replaced computers included those used to run the Joint Staff's combat models. All of these combat models needed to be converted to run on the new machines and tested to ensure that they produced the same results as before. See Converting Combat Models from IBM to Honewell for details.
We determined the four categories of documentation were required to ensure the proper use of combat models: Users Manual, Analysts Guide, Program Maintenance Manual, and source code commenting.
The Users Manual describes the purpose of the model and the purpose, general function, and operational characteristics of the various system components. It also includes instructions for preparing inputs and interpreting outputs, with examples. The intent is to supply the necessary information for using the combat model.
The original name for this category was simply "Technical Memorandum." This name was changed to the more descriptive name, "Analysts Guide." The Analysts Guide describes the mathematical details of the process models of the combat model and the algorithms in these process models. The intent is to supply the necessary information for understanding how the combat model works and why it works that way. This information is needed for non-standard uses and to support validation of the model.
Program Maintenance Manual
The Program Maintenance Manual includes the technical details of the combat model's implementation. Subsections include logic descriptions, source code listings, variable glossaries, and input/output record descriptions. The intent is to support later changes to the code and investigation of anomalies in the model's use.
Source Code Commenting
During the course of the conversion process, we discovered the critical importance of complete commenting of the source code. These comments should describe each function of the source code and each algorithm within the code. The intent is to place any needed information about the code as close to the place where it will be needed as possible - withing the code itself.
If you arrived here using a keyword shortcut, you may use your browser's "back" key to return to the keyword distribution page.
Return to Hartley's Projects Page