Below is the uncorrected machine-read text of this chapter, intended to provide our own search engines and external engines with highly rich, chapter-representative searchable text of each book. Because it is UNCORRECTED material, please consider the following text as a useful but insufficient proxy for the authoritative book pages.
DOCUMENTATION FOR MICROSIMULATION MODELS: A REVIEW OF TRIM2, MATH, AND HITSM 346 COMPARISONS WITH IEEE STANDARDS The last step in this review was an evaluation of the microsimulation model documentation using the content requirements for model documentation from IEEE Standards for Software User Documents (IEEE, 1988). Table 1, taken from the standard, summarizes the inclusion requirements, which are discussed below. â¢ Title page A title page is mandatory and must include (1) the document's name, (2) its version and date, (3) the software covered, and (4) the issuing organization. All but one of the documents reviewed has a title page (the exception was the MATH User's Guide). The HITSM document conforms to the standard. The MATH and TRIM2 documents that have title pages do not reference a document version but otherwise generally conform to the standard. â¢ Restrictions When restrictions apply to using or copying a document or software product, their identification is mandatory on the title page or immediately following the title page. None of the documents reviewed has restrictions. â¢ Warranties and contractual obligations Warranties, contractual obligations, or disclaimers should be in a separate section in the documentation or there should be a reference to where the information can be found. None of the documents reviewed has either. â¢ Table of contents A table of contents is necessary in documents over 8 pages long. The TRIM2 Reference Manual has a simple table of contents at the beginning as well as comprehensive ones for each major section. All of them lack page numbers. The TRIM2 Simulation Modules has a simple table of contents at the beginning of the first and second volumes (unnumbered) and a comprehensive one at the beginning of each section. The TRIM2 Codebook has a comprehensive table of contents at the beginning of the document. The MATH Technical Description has a simple table of contents at the beginning of the document but none preceding major sections. The MATH User's Guide has a simple table of contents at the beginning of the document (the pagination system was indecipherable) and a comprehensive table of contents at the beginning of each section. The MATH Codebook has no table of contents. HITSM has a comprehensive table of contents at the beginning of the document. â¢ List of illustrations A list of the titles and locations of all illustrations contained in a document is optional. The TRIM2 Reference Manual has such a list preceding each major section. Neither the TRIM2 Simulation Modules nor the TRIM2 Codebook has a list of illustrations. The MATH User's Guide has lists in each major section, but neither the MATH Technical Description nor the MATH Codebook has lists. The HITSM documentation does not have a list of illustrations either. â¢ Introduction The IEEE standard requires the following in the introduction: audience description, applicability statement, statement of purpose,
DOCUMENTATION FOR MICROSIMULATION MODELS: A REVIEW OF TRIM2, MATH, AND HITSM 347 TABLE 1 IEEE Standard Inclusion Requirements Component Single-Volume Document Multi-Volume Document 8 Pages or Less More Than 8 Pages First Volume Other Volume Title page M M M M Restrictions M M M M Warranties R R R R Table of contents O M M M List of illustrations O O O O Introduction Audience description R M M R Applicability M M M M Purpose R M M R Document usage R M M R Related documents R R R* R Conventions M M M R Problem reporting R M M R Body Instruction mode 1 1 1 1 Reference mode 1 1 1 1 Error conditions R R R R Appendixes O O O O Bibliography M M M** M** Glossary M M M** M** Index 2 2 M** M** Key: M Mandatory-Shall be included when information exists. O Optional. R ReferenceâEither include the section or a reference to where the information can be found within the document set. * Shall address relationship to other volumes. ** Mandatory in at least one volume in the document set, with references to information in other volumes. 1 Every document has a body, each document set shall address the instructional and reference needs of the audience. Required content is in 5.7.1 and 5.7.2. 2 An index is mandatory for documents of 40 pages or more and optional when under 40 pages. SOURCE: Institute of Electrical and Electronics Engineers, Inc. (1988: Table 2).
DOCUMENTATION FOR MICROSIMULATION MODELS: A REVIEW OF TRIM2, MATH, AND HITSM 348 document usage description, related documents, conventions, and problem reporting instructions. The audience description indicates what parts of the documentation are intended for which audiences and the experience levels of the audiences. The applicability statement indicates the version of the software that is documented and the required hardware and software environments. The conventions section summarizes the symbols, stylistic conventions, and command syntax conventions used in the document. The other sections of the introduction are self-explanatory. All three sets of documentation for TRIM2, MATH, and HITSM have introductory sections that are reasonably good statements of purpose. In addition, the introduction to the TRIM2 Reference Manual relates the manual to the other documents in the set and briefly indicates the intended audiences. The introductions in both the TRIM2 Reference Manual and the MATH Technical Description discuss hardware and software environments. The MATH User's Guide has no introduction. The HITSM documentation is a single volume, so some of the parts of the required introduction would not be relevant; it does not include an audience description or applicability statement. The preface in the TRIM2 Simulation Modules has excellent instructions for reporting problems, and it solicits comments and suggestions from readers. None of the other documents pays attention to this matter. â¢ Body of document The IEEE standard distinguishes between instruction mode and reference mode documents. Instructional documents are intended to provide the reader with the information necessary to operate the software. Reference documents are intended to provide the reader with easy access and random access to information about all aspects of the software. The standard requires slightly different contents for each mode. But it exhorts the producers of the documentation that âin either mode, use a consistent organizational structure based on the expected use of the document, providing examples as necessaryâ (IEEE, 1988:10). The standard suggests the following contents for these two modes of documentation: Instructional Mode Reference Mode Scope Purpose Materials Materials Preparations Preparations Cautions and warnings Input(s) Methods Cautions and warnings Related information Invocation Suspension of operations Termination of operations Output(s) Error conditions Related information
DOCUMENTATION FOR MICROSIMULATION MODELS: A REVIEW OF TRIM2, MATH, AND HITSM 349 In the IEEE standard the instructional mode document may be thought of as a tutorial. The scope is simply a statement at the beginning of the document indicating the material that is to be covered. The materials and preparations sections indicate items the user will need to complete the tutorial. Cautions and warnings help learners avoid major problems that may result from mistakes in using the tutorial. The methods section is really the body of the instructional document and describes what the learner must do, how to invoke functions, possible errors, and expected results. Finally, related information provides other useful information to the user, such as tasks frequently performed together or constraints and limitations. Chapter II of the TRIM2 Reference Manual is the only part of all of the documentation reviewed that could be considered to be written in an instructional mode. Most of the IEEE's required components can be found in this chapter, albeit not in the specific order listed above. If there is a deficiency, it is in not providing explicit cautions and warnings. For example, the chapter warns against excessive numbers of household dumps or excessive numbers of observations to be processed in a test or homework run, without telling the reader how many are too many. The body of a reference mode document contains material about the model's software. Each section begins with a statement of purpose. The materials and preparations sections concern items needed to operate the particular function of the software. The inputs section describes all data required to process the function correctly. Cautions and warnings refer to unintended consequences from applying the function being described. The invocation section provides all the information needed to use and control the function. The sections on suspension and termination of operations describe how to interrupt and how to recognize normal and abnormal terminations. The outputs section discusses the outputs to be expected from executing the function, including hard copy or screen displays and changes to files or data. Error conditions refer to common errors that could occur while executing the function. Related information would include limitations and constraints, related functions, and notes. Most of the chapters in the TRIM2 Reference Manual, TRIM2 Simulation Modules, MATH Technical Description, MATH User's Guide, and HITSM documentation are reference mode documents that refer to major sections of the respective models. In general, the chapters are complete in their descriptions of purpose, inputs, and outputs. With the exception of HITSM, they also satisfactorily describe invocation information. If these chapters have a weakness relative to the IEEE standard, it is their lack of cautions and warnings and typical lack of discussion of error conditions. â¢ Error messages, known problems, and error recovery The IEEE standard suggests that this section must be included in a documentation set and reference to this must be provided within each volume of the set None of the documents reviewed has such a section or reference.
DOCUMENTATION FOR MICROSIMULATION MODELS: A REVIEW OF TRIM2, MATH, AND HITSM 350 â¢ Appendixes The IEEE standards suggest that optional appendixes are be useful for (1) detailed input and output data, (2) âcodesâ used in input or output, (3) interactions between tasks or functions, (4) global processing limits, (5) descriptions of data formats and file structures, and (6) sample files, reports, or subprograms. The documentation for all three models has appendixes that provide descriptions of data formats. In HITSM there is an explicit appendix. In TRIM2 and MATH it is a separate Codebook document. Apart from these, all of the documents suffer from having excessively long input lists (e.g., program parameters that vary by state and by year) in the middle of the text. Such input lists should appear in appendixes. â¢ Bibliography A bibliography is mandatory according to the IEEE standard. The HITSM document does not have a bibliography. The MATH Technical Description has a bibliography for the introductory chapter but none for the rest of the document. The TRIM2 CPS Codebook document has a bibliography, but the Reference Manual does not. Some of the individual sections in the Simulation Modules binders have reference lists at the end of the âPurposeâ or text section (see, e.g., the FSTAMP chapter), but the Simulation Modules binder lacks a single bibliography or a standard reference list or bibliography for each chapter. â¢ Glossary The IEEE standard requires a glossary for all documentation sets; however, none of the documents reviewed has one. â¢ Index As with a glossary, an index is required for all documents. Again, none of the documents reviewed has one. (The MATH Codebook has two sections near the front, entitled âalphabetical variable indexâ and âsequential variable index;â however, neither functions as an index in the sense of the IEEE standard.) In short, the documents reviewed had many of the components required of good documentation. They were particularly compliant with respect to the major itemsâstatements of purpose, inputs, methods, and so forth. The components that were lacking, however, were precisely those that would allow a user to use the documents easily. Users of software documentation know how crucial an index is, and yet none of the microsimulation model documentation reviewed here had one. Before these models can be widely used, a major emphasis must be put on organizing and editing the documentation. The current documentation impedes, rather than facilitates, acceptance of these models.