Model Documentation Standards for Financial Models
Executive Summary
Key Takeaways
- ✓ An institutional financial model requires a documentation package comprising an assumption log, version history, model map, instructions for use, known limitations, and a glossary of key terms.
- ✓ Documentation enables the model to be operated and verified by parties other than its original developer, and provides the audit trail required for governance and regulatory purposes.
- ✓ The ICAEW Financial Modelling Code and the FAST Standard both establish specific documentation requirements that define institutional expectations.
- ✓ Documentation must be maintained throughout the model's life and updated whenever the model changes.
- ✓ Models submitted without adequate documentation may not satisfy lender conditions precedent or institutional governance requirements.
Institutional Definition¶
A financial model without adequate documentation is incomplete as an institutional deliverable, regardless of the quality of its calculations. Documentation serves three distinct functions: it enables a model's outputs to be understood by parties other than its developer; it provides the audit trail required to verify that the model's inputs are appropriate; and it records the model's history in a form that supports future revision and governance.
Why Model Documentation Matters¶
Operability by Third Parties¶
A financial model is often operated by people who did not build it. Lenders who stress-test a project finance model, investment committee members who interrogate an acquisition model, and successors who inherit a portfolio company model from a departed colleague all need to understand the model's structure and assumptions without access to the original developer. Without documentation, the model is only fully usable by the person who built it, creating a key-person dependency and a governance failure.
Audit and Verification¶
When a model is submitted for independent review, the reviewer must be able to trace every material assumption to a documented source and verify that the model's structure implements the intended relationships. An auditor who cannot identify where a key assumption comes from, or why a particular structural choice was made, cannot complete a thorough review.
Regulatory and Legal Defensibility¶
In contexts where a model's outputs are relied upon for regulatory reporting, covenant testing, or legal proceedings, the model's documentation forms part of the evidence base. A model with no documentation of its assumptions, version history, or known limitations is difficult to defend if its outputs are challenged.
Change Management¶
A model that lacks documentation of its intended structure and the rationale for its design choices is vulnerable to inadvertent corruption during revision. Revisions made without understanding the model's design may introduce errors that are not detectable without reference to the original design documentation.
Components of an Institutional Model Documentation Package¶
1. Assumption Log¶
What it is. A record of every input and assumption in the model, stating: the assumption name, the value used in each scenario, the source of the value (market data, contractual term, management estimate), the date the value was last confirmed, and the person responsible for it.
Why it is required. The assumption log is the primary audit trail for a model's inputs. An auditor, lender, or investor who examines the model's inputs can verify each assumption against its stated source. Without an assumption log, assumptions are unverified assertions.
Minimum standard. Every assumption that materially influences a key output metric must be documented in the assumption log. The log should be updated whenever an assumption is revised, with the previous value, the new value, the date of the change, and the reason for the change.
ICAEW requirement. The ICAEW Financial Modelling Code requires that all inputs be clearly documented and traceable to authoritative sources.
2. Version History¶
What it is. A record of all material changes to the model, stated in reverse chronological order: the version number or date, the description of the changes made, the person who made the changes, and the reason for the changes.
Why it is required. The version history provides the historical record of the model's evolution. It allows a reviewer to understand how the model has changed since a previous review, identifies who made each change, and provides context for any current feature that may appear unusual (because it was introduced to address a specific issue at a specific time).
Minimum standard. Every version of the model that was shared with a third party, used as the basis for a decision, or marked as a formal release should appear in the version history with sufficient detail to distinguish it from the preceding version.
FAST Standard requirement. The FAST Standard requires a version control system for all models, with version identifiers embedded in the model and a version history maintained as part of the documentation package.
3. Model Map¶
What it is. A description of the model's worksheet structure: the purpose of each worksheet, the sequence in which worksheets should be read, the location of key inputs, the location of key outputs, and the dependencies between worksheets (which worksheets feed into which other worksheets).
Why it is required. A model map enables a new user or reviewer to navigate the model efficiently and understand its structure before examining its detail. Without a model map, understanding the structure of a complex model requires reverse-engineering the dependency relationships, which is time-consuming and error-prone.
Minimum standard. The model map should cover all worksheets, including hidden worksheets, and should indicate the direction of information flow at the worksheet level.
4. Instructions for Use¶
What it is. A description of how to operate the model: which cells are input cells, how to switch between scenarios, how to run sensitivity analysis, what outputs the model produces, and any specific steps required to refresh calculations or update data connections.
Why it is required. Instructions for use are required whenever a model is operated by someone other than its developer. They prevent errors arising from misuse of the model's interface.
Minimum standard. Instructions should cover: the input process (where to enter assumptions, in what order, and with what constraints), the scenario selection mechanism, and the output reading process (which outputs are primary, where they are located, and what they measure).
5. Known Limitations and Caveats¶
What it is. A statement of the model's known limitations: calculations that are approximations rather than exact implementations, aspects of the financial relationship that the model does not capture, assumptions that are particularly uncertain, and scenarios in which the model's outputs may not be reliable.
Why it is required. All financial models are simplifications of complex financial relationships. The decision-maker who relies on the model's outputs deserves to know what the model does not capture as well as what it does. Undisclosed limitations may affect the reliability of the model's outputs in ways that are not apparent from examining the model itself.
Minimum standard. Any calculation that is an approximation rather than an exact implementation should be noted. Any assumption that is particularly uncertain (because it relies on a market forecast, a management estimate, or historical data with limited applicability) should be flagged. Any scenario type in which the model has not been tested should be identified.
6. Glossary of Terms¶
What it is. Definitions of the key terms used in the model, particularly any terms that have a specific meaning within the model that differs from their general use, or that are defined differently in the model than in the underlying transaction documents.
Why it is required. Definitional consistency is a specific model risk: a DSCR calculation in the model that uses a different definition of "cash available for debt service" from the definition in the loan agreement is a material error that can only be detected if both the model's definition and the contractual definition are clearly stated.
Documentation Location and Format¶
In-Model Documentation¶
Some documentation elements are most effectively maintained within the model workbook itself:
- Assumption log: typically a dedicated worksheet named "Inputs", "Assumptions", or "Control" that lists all assumptions with their values and sources
- Instructions for use: a "Read Me" or "Instructions" worksheet at the front of the model
- Model map: a "Structure" or "Map" worksheet describing the worksheet inventory and dependency flow
- Known limitations: a cell comment or dedicated section on the Control worksheet
External Documentation¶
Other documentation elements are more appropriately maintained as separate files accompanying the model:
- Version history: may be maintained as a separate change log document or within a version control system (see Version Control for Financial Models)
- Assumption source documentation: the underlying source materials (market studies, term sheets, management accounts) that support the assumption log values
- Technical specifications: for complex models, a separate technical document describing the mathematical relationships implemented in the model
Documentation Assessment in Model Audits¶
When a financial model is submitted for independent audit, the auditor assesses the adequacy of its documentation package against the following criteria.
Completeness. Does the documentation cover all required components? Are all assumptions documented? Does the version history cover all relevant versions?
Accuracy. Does the documentation accurately describe the model as it currently exists? Does the model map reflect the actual worksheet structure? Does the assumption log reflect the values currently in the model?
Currency. Is the documentation up to date? Does the version history include the most recent version? Are assumption sources current?
Traceability. Can every material assumption be traced from the assumption log to a supporting source? Are the sources identified in the assumption log accessible?
Accessibility. Is the documentation accessible to a user who did not build the model? Are the instructions for use sufficient to enable independent operation of the model?
Common Mistakes¶
| Common Mistake | Why It Matters |
|---|---|
| Treating documentation as a final step rather than an ongoing requirement | Documentation that is created at the end of a model's development, after all the design decisions have been made, is less accurate and less complete than documentation maintained throughout development. The assumption log should be updated each time an assumption is revised, not reconstructed from memory after the model is complete. |
| Failing to update documentation when the model changes | A model that has been significantly revised since its documentation was written has documentation that describes a different model. Outdated documentation is worse than no documentation because it misleads rather than informs. |
| Documenting inputs but not the rationale for structural choices | Documentation that records what assumption values are used but not why specific structural choices were made (why a particular DSCR definition was chosen, why a specific depreciation method was applied) fails to provide the design context that future users and reviewers need. |
| Including documentation that does not cover hidden worksheets | A model map that does not mention hidden worksheets creates a false impression of complete documentation. All worksheets, including hidden ones, must be covered. |
Regulatory and Industry Context
ICAEW Financial Modelling Code. The Code establishes comprehensive documentation requirements including: documented assumptions with sources, version history, model map, instructions for use, and known limitations. It treats documentation as a core quality attribute of the model, not an optional supplement.
FAST Standard. The FAST Standard includes specific documentation requirements: a version control protocol, an assumption documentation convention, and a structural documentation approach. FAST-compliant models are expected to be self-documenting to a significant degree through the consistent application of the Standard's structural conventions.
Project finance lender requirements. Lenders who commission independent model audits before financial close typically require the model submission to include an assumption log and a version history as minimum documentation. Models submitted without this documentation may not satisfy the lender's conditions precedent.
Model Risk Management frameworks. Regulated financial institutions operating under model risk management frameworks (Federal Reserve SR 11-7, PRA SS1/23) are required to maintain documentation for all models used in material decisions, including documentation of the model's purpose, its inputs and outputs, its limitations, and its validation history.
Worked Example
Scenario. An infrastructure fund manager submits an airport concession model for review by a new investment committee that did not participate in the original investment decision. The model was built three years ago. The fund manager provides the model file but no accompanying documentation.
Assessment findings. - No assumption log: the committee cannot determine where the traffic growth assumptions came from, whether they were based on a traffic study, and whether the traffic study has been updated since the model was built. - No version history: the committee cannot determine how the model has changed since the original investment decision, or whether any revisions have been made to reflect actual operating performance versus original projections. - No model map: the model has 31 worksheets. The committee's analyst spends two days tracing the calculation structure before being able to verify the IRR calculation. - No instructions for use: the analyst is unable to determine how to switch the model between the base case, the downside case, and the lender's stress case without running the risk of corrupting the model's structure.
Impact. The committee's review is extended by five business days while the analyst reconstructs the missing documentation by reverse-engineering the model. Two material issues are identified: the traffic growth assumption in Year 5 is different from the assumption noted in the original investment memo (no documentation to explain the discrepancy), and the model map reveals a hidden worksheet containing interim calculations that affect the concession fee payment schedule.
Resolution. Documentation standards are adopted as a requirement for all models submitted for committee review, with a minimum documentation package specified and the model manager required to certify completeness before submission.
Further Reading¶
- ICAEW, Financial Modelling Code, Institute of Chartered Accountants in England and Wales
- FAST Standard Organisation, FAST Standard for Financial Modelling
- Federal Reserve, SR 11-7: Guidance on Model Risk Management, Board of Governors of the Federal Reserve System
Continue Reading¶
Prerequisites¶
- Financial Model Governance — the parent pillar covering the broader framework within which documentation standards sit
Related Technical Guides¶
- Version Control for Financial Models — the specific guide to version history management
- Model Standards — the broader coverage of FAST and ICAEW standards
Related Glossary¶
- Audit Trail — the glossary definition of the audit trail concept in a financial model context
- FAST Standard — the modelling standard that establishes documentation requirements
Related Checklists¶
- Model Handover Checklist — the operational checklist for model transfers that includes documentation requirements
Related Products¶
- Financial Model Audit Engine (FMAE) — deterministic structural auditing referenced throughout this guide
How OXXON tests thisRun a free structural check with FMAE
Frequently Asked Questions
How long should a model's documentation package be?
There is no standard length requirement. The documentation should be sufficient to enable an independent party to understand the model's structure, verify its inputs, operate it correctly, and understand its limitations. For a simple single-period model, this may be a few pages. For a complex multi-tranche project finance model, it may be a comprehensive reference document.
Should documentation be inside the model or in a separate file?
Both approaches have merit. In-model documentation (worksheets within the workbook) travels with the model and is always associated with the correct version. Separate file documentation can be more extensive and formatted for reading rather than display in a cell. Best practice for institutional models is to include minimum documentation (assumption log, model map, instructions for use) within the model, and to maintain extended documentation (version history, technical specification, source materials) in a separate package.
Who is responsible for maintaining model documentation?
The model owner — the individual or team responsible for the model's accuracy and governance — is responsible for maintaining its documentation. For models with multiple contributors, there should be a designated owner with overall responsibility for documentation completeness and accuracy.
Is documentation required for internal models as well as external submissions?
Yes. Models used internally for planning, budgeting, and portfolio monitoring carry the same governance requirements as models submitted externally. The risk of operating from an undocumented internal model is the same as the risk of relying on an undocumented external submission.
What is the minimum documentation for a model submitted to a lender?
At minimum: an assumption log listing all material inputs with their sources, a version history showing the current version and any prior versions submitted to the lender, and a brief description of the model's structure. Most lenders' technical advisers will expect this as the baseline for a model audit.
Related Articles
Version Control for Financial Models
Version control for financial models is the systematic management of changes to a model over time, ensuring that each version of the model is identifiable, that all material changes are recorded with their date and author, and that previous versions can be recovered when needed. Unlike software version control systems (such as Git), financial model version control is typically implemented through a combination of file naming conventions, an in-model change log, and an archive of previous model files. The FAST Standard and the ICAEW Financial Modelling Code both require a version control protocol as a core component of institutional model governance.
Financial Model Standards
The two principal standards governing institutional financial model construction are the ICAEW Financial Modelling Code, published by the Institute of Chartered Accountants in England and Wales, and the FAST Standard, published by the FAST Standard Organisation. Both standards address the structure, documentation, and transparency requirements for financial models intended for institutional use, including models submitted for lender review, investment committee approval, and regulatory reporting. The standards differ in their scope and approach: the ICAEW Code provides principles-based guidance applicable to all financial models, while the FAST Standard provides prescriptive rules for model structure applicable to models built under the FAST methodology.
Real Estate Financial Modelling
Real estate financial modelling spans two structurally distinct disciplines: development appraisals, built forward from land and construction cost through phased sales or leasing velocity to a gross development value, and income-producing asset models, built from stabilised net operating income to an exit value using direct capitalization or a discounted cash flow. This page is the hub for the Knowledge Centre's real estate modelling content: the two model families, how gross development value and residual land value are built, waterfall and promote mechanics, and how each major property type — residential, office, retail, industrial and logistics — specializes the base structure to its own revenue drivers.