Model documentation an examiner accepts

Documentation is a reproduction test

The single most useful reframing we can offer is this: model documentation is not a description of a model. It is the evidence that the model can be understood, challenged and taken over by somebody other than the person who built it. Every requirement in every framework we have read reduces to that, and once you hold it, most of the arguments about templates and page counts dissolve.

It explains why reviewers ask questions that feel picky. Why does the feature definition need a code reference? Because otherwise nobody can reproduce it. Why do you need the exact data vintage? Because otherwise nobody can reproduce the reported performance. Why do you need to state what the model is not for? Because a model that has never had its boundaries written down will eventually be used outside them by someone acting in good faith.

It also explains the most common failure. Teams write the document at the end, from memory, as a deliverable. The result is a description of intentions rather than a record of what happened, and a reviewer discovers this within an hour by trying to tie a number in the document to a number in the code.

What the guidance actually asks for

In United States banking, the anchor is the 2011 joint supervisory guidance on model risk management issued by the Federal Reserve and the Office of the Comptroller of the Currency, which the Federal Deposit Insurance Corporation later adopted for the institutions it supervises. It is worth reading in full; it is unusually plain-spoken for a regulatory document, and it has aged well against machine learning despite predating most of it.

Four ideas from it carry nearly all the weight.

The definition is broad. A model is a quantitative method that applies theories, techniques and assumptions to turn input data into estimates. That covers a spreadsheet with a regression in it, a vendor scorecard, a rules engine with tuned parameters, and a gradient-boosted tree. Teams routinely under-scope their inventory by assuming a model means something built by data scientists.

Validation has three core elements: evaluation of conceptual soundness including the developmental evidence, ongoing monitoring including process verification and benchmarking, and outcomes analysis including back-testing. If your package cannot support all three, it is not complete, whatever its length.

Effective challenge is the governing idea — critical review by objective, informed parties with the standing to force a change. Documentation exists to make that possible. A document a challenger cannot use to challenge you has failed at its only job.

Proportionality is explicit. The expected rigor scales with the model's materiality and complexity. A low-tier internal estimator does not get the treatment a capital model gets, and building your program as though it does will exhaust the team on the wrong models.

Outside banking the vocabulary changes and the substance does not. Actuarial standards cover modeling practice for insurers. The voluntary United States AI risk management framework organizes the same concerns under govern, map, measure and manage. There is an international management system standard for AI. And where a product is placed on the European market, the AI Act sets out technical documentation contents for systems classified as high risk, with obligations phasing in over several years — confirm the classification and the applicable dates for your specific product rather than assuming. Different words, same reproduction test underneath.

The package, and who each piece is for

A complete package is a small number of artifacts with distinct audiences. Confusing them is why documents get long and still leave gaps.

Three of these are commonly weak. The data documentation is usually a dictionary rather than a lineage, so nobody can trace a field to its source system or say what a sample exclusion did to the population. The monitoring results exist as dashboards rather than as a retained record, so the plan is documented and its execution is not. And the change log is a wiki page updated when someone remembers, which is the artifact most likely to be contradicted by the repository during a review.

The cold-start test

Here is a test you can run this week, at no cost, that predicts how a review will go better than any checklist.

Take somebody competent who has never worked on the model — another team's engineer, a quantitative colleague, a new hire. Give them the package and nothing else. No access to the author. Then ask for four things: state in two sentences what the model does and what decision it feeds; name the data and the exact time period the reported performance was measured on; reproduce one headline number from the described inputs; and name the three conditions most likely to make this model wrong.

Watch where they get stuck, and fix that. In our experience the sticking points cluster: a feature described in words that does not match how it is computed, a performance figure with no stated sample or period, a target definition that turns out to have changed mid-project, and a limitations section written so generically that it names nothing specific.

The fourth question is the one that separates good packages from complete ones. A document that can tell a stranger what breaks the model is a document written by people who understand it. A document that cannot has usually recorded activity rather than understanding.

Make the document a build artifact

The structural fix, and the one worth engineering effort, is to stop writing documentation as prose that references the pipeline and start generating it from the pipeline.

Concretely: the narrative lives in the repository next to the code. Every number, table and figure in it is produced by the run, not pasted from one. The document build fails if a referenced metric was not produced. Each released document carries the commit hash of the code, the identifier and hash of the data snapshot, the environment specification, and the run identifier that produced the figures. The output is versioned and archived with the model artifact.

The effect is that version drift becomes impossible rather than merely discouraged. When a reviewer asks whether the document describes the deployed model, the answer is a hash comparison instead of an investigation. When the model is retrained, a fresh document is a byproduct rather than a project. And when the author leaves, what remains is a document that was never separable from the thing it describes.

This costs a week or two the first time and very little afterward. It is the highest-return engineering work in the whole area, and it is almost never anyone's assigned task.

Limitations, written so they help you

Teams soften limitations sections because they read as admissions. That instinct is backwards in this specific setting, and understanding why is worth the paragraph.

A limitation you have written down, with a control attached, is a managed risk. The same limitation found by a validator is a finding, and it arrives with a remediation date and a paper trail. The content is identical; only the ownership differs. Volunteering it is not candor for its own sake — it is the cheaper of two ways for the same fact to reach the record.

So write each limitation as three sentences. What the limitation is, stated specifically enough to be falsifiable. What control reduces the risk it creates — a human review step, a scope restriction, an override, a fallback. What monitoring would detect it if it started to bite, and at what threshold. A limitation with a control and a detector is a risk being managed. A limitation on its own is an open issue somebody else will now own.

Be specific. “The model may perform differently on new populations” tells a reader nothing. “Training data contains fewer than four hundred observations from the western region, so segment performance there is not measurable at useful precision; the region is excluded from automated decisions and routed to manual review; segment volume and outcome rates are reported monthly” tells them everything, and it closes the question instead of opening it.

Use restrictions deserve the same treatment and are more often missing entirely. State what the model must not be used for, which populations are out of scope, what inputs invalidate the output, and what happens when the model is unavailable. Models get reused. The document is the only thing standing between a reasonable colleague and a use nobody intended.

Vendor models and models you cannot see inside

Buying a model does not transfer the risk of using it, and supervisory guidance is direct about this: the institution using a vendor model is responsible for validating it and should require developmental evidence from the vendor.

In practice vendors vary from generous to flatly unwilling. When you cannot see inside, the position that holds up is documented compensation rather than a shrug. Record exactly what the vendor did and did not provide, and the date you asked. Build an in-house challenger — even a simple one — and benchmark against it on your population. Increase the weight of outcomes analysis, because if you cannot inspect the mechanism you must observe the results more closely. Document the contingency plan for the vendor discontinuing the model, changing it underneath you, or failing. And negotiate for the artifacts up front, while you still have negotiating room.

Systems built on hosted language models sit in this category whether or not anyone has classified them that way. The dependency is a model you do not control, that can change without notice, whose behavior is not deterministic by default. Document the provider and version, the sampling settings, the prompt as a versioned artifact, the retrieval corpus and its snapshot, the guardrails, the evaluation set with its results, and what happens when the provider is unavailable or the version is retired. That is the same package with different nouns, and building it is what turns an internal prototype into something a regulated buyer can actually deploy.

When all of this is too much

If you run three low-materiality models in a small firm, a heavyweight program will consume the team and produce paper. The proportionality principle exists precisely for you, and using it is not cutting corners.

The minimum that is genuinely worth doing: a real inventory with an owner and a tier for every model, including the spreadsheets; a ten-page development document per model that passes the cold-start test; a monitoring plan with thresholds and a retained record showing it ran; and someone other than the developer signing that they reviewed it. That is a weekend of setup and a few hours per model, and it is worth more than a ninety-page template filled in by the person who built the model and read by nobody.

What you should not do is buy governance software before you have written one good document by hand. The tool will hand you a template, the template will get filled in, and you will have the paperwork without the reproduction test — which is exactly the failure mode this article exists to describe.

The mistakes we see

• Documentation written at the end, from memory, as a deliverable rather than a record
• Performance figures with no stated sample, period or population
• Feature descriptions that do not match the code that computes them
• No data lineage, so exclusions and their effect on the population are invisible
• A monitoring plan with no evidence it was executed
• Thresholds with no attached action, so a breach produces a chart and nothing else
• Generic limitations that name no specific condition and attach no control
• No use restrictions, so reuse outside the intended scope is undetectable
• Validation performed by the developer, or by someone with no standing to force a change
• A vendor model documented as a black box with no compensating analysis and no record of what was requested

Before the next review

• Every model is in an inventory with an owner, a tier and a status
• Purpose, intended use and use restrictions are stated on the first page
• Data sources, vintages, exclusions and known defects are documented
• Every reported metric names its sample, period and population
• Alternatives considered are recorded, with the evidence that decided it
• Every limitation has a control and a detection threshold
• The monitoring plan states thresholds, owners and the action on breach
• Monitoring results are retained as a record, not only as a dashboard
• The document carries the code commit, data snapshot and environment it describes
• Figures and numbers are generated by the pipeline, never pasted
• An independent party has reviewed it and can force a change
• Someone who has never seen the model has passed the cold-start test on it

Bottom line

Write the documentation for the person who will inherit the model, not for the file. Say what it does, what it was measured on, what it must not be used for, and what would break it. Generate the numbers from the pipeline so the document cannot drift from the code. Keep the monitoring evidence, not just the monitoring plan. Do that and the review becomes a conversation about the model, which is the conversation you want, rather than a search for the numbers, which is the one you do not.

Frequently asked questions