Model documentation is a formal (official, approved) collection of documents and data that provides detailed explanation of the rationale, assumptions, derivations, tests and other analyses that support the use of a model for a given purpose.
Why is documentation so important? Because it is the next best alternative to continuous access to a modeler's thought process.
A model exists in three forms:
- conceptual mathematical representations inside the modeler's head
- the programmed version (digital form) and
- on paper as and if documented.
Even if transient and fickle, the modeler's internal version is the richest representation of the model. It automatically comes with the cloud of nearby models that the modeler tried and rejected, and all approximations, shortcuts and assumptions that were made during the development process.
The programmed version on the other hand, is the "legal" manifestation of the model. This is the version that is put in production, supports decisions etc. etc. It is almost always an approximation to the intended model. Documentation bridges the gap between the actual programmed model and the developer's thought process and justification.
Issues and Challenges
- No public standards for what constitutes adequate model documentation