What a Model Document Must Contain
The standard set of sections a model document needs so that someone who didn't build the model can still understand, validate, and eventually retire it.
Prerequisites: Model Inventory and Risk Tiering
The researcher who built a model always understands it. The problem is everyone else: the validator checking it before it goes live, the risk manager trying to explain a bad month to a client, the new hire who inherits it two years later after the original author has left the firm. A model document exists for all of them. It's not a description of the code — it's an explanation of the model written for someone who has never seen the code and never will.
A usable model document walks through a fixed set of questions, in order. What problem does the model solve, and what decision does its output feed into? What data does it use, and what are that data's known limitations — survivorship gaps, revision history, vendor outages? What are the model's core assumptions, and under what conditions would those assumptions plausibly break (a regime shift, a liquidity crunch, a change in market structure)? What did the validation testing actually show — not just "backtested Sharpe of 1.4," but what was tested, over what period, and what wasn't tested because the data didn't support it? And finally, what are the known limitations the model owner would want a new user to know before relying on it?
That last section is the one most documents skip, and it's the one that matters most. Every model has edge cases where it's known to misbehave — a volatility filter that's untested during a market halt, a factor model that assumes a stock universe that doesn't include newly listed names. Writing those down isn't an admission of weakness; it's what separates a documented limitation from a surprise discovered during a live incident.
The document also has to stay current. A model document written at launch and never touched again is worse than no document, because it actively misleads a reader into trusting stale assumptions. Every material change to the model — a parameter recalibration, a new data source, a change in how the output is used downstream — should trigger an update to the document, not just to the code.
A model document is written for a reader who never saw the code: what problem it solves, what data and assumptions it relies on, what was actually tested, and what its known limitations are. It needs updating every time the model changes materially, not just at launch.
If you can't write the "known limitations" section honestly, that's a signal the model hasn't been stress-tested enough yet — not a reason to leave the section blank.
Further reading
- Federal Reserve SR 11-7, Guidance on Model Risk Management