What documentation does a model need before it goes live?

Intended use, and the boundary around it

The document starts with what decision this model informs, for which population, at what point in a process, and with what human involvement. Not the architecture, not the metrics — the decision. "Scores inbound card payments between one and five thousand pounds for the probability of chargeback, in the authorisation path, with scores above the high threshold routed to manual review rather than declined automatically" is a usable statement. "Fraud detection model" is not, because nothing can be evaluated against it.

The half that gets omitted is the boundary: what this model is explicitly not for. Out-of-scope uses matter because the realistic governance failure is not a model behaving badly on the job it was built for, it is the same model quietly acquiring a second job. A propensity model built for marketing prioritisation gets wired into a pricing decision, and nobody re-evaluated it because it was already approved. Naming the excluded uses turns that from an accident into a policy breach somebody can point at, which is the whole mechanism by which written scope has any effect.

State the population too, since it constrains everything downstream. If the model was trained and evaluated on one market's customers, that is a limit on where it may be deployed, and it is the sentence that stops someone launching it in a second market on the assumption that a model is a model.

Where the data came from and whether you were allowed to use it

Provenance has three parts and teams typically document only the first.

Lineage: which sources, which tables or feeds, which time period, how they were joined, what filtering and sampling was applied, and the immutable identifier of the exact dataset version used — a snapshot or commit identifier, not a description of a moment. Include the label definition, because a label is an interpretation and reasonable people define "churned" differently.

Legal and contractual basis: the lawful basis for processing the personal data involved, the licence terms of any purchased or scraped dataset, and any contractual restriction on using a vendor's data to train a model. This is where retrospective problems are most expensive, because unwinding a model trained on data you were not entitled to use means retraining from scratch and possibly deleting derived artefacts. It also has to record the retention and deletion position: if a subject exercises a deletion right, what happens to the training set and to the model.

Known characteristics of the data: which groups are under-represented and by how much, what the class balance is, what preprocessing decisions were made and what they assume, and which known defects were left in. A reviewer can reason about a documented imbalance. They cannot reason about one they have to discover.

Evaluation, and the part that must be per segment

Aggregate metrics on a held-out set are the beginning. The pack needs the metric definitions, the threshold and how it was chosen, the composition and time period of the evaluation set, and confirmation that the split respects time — a random split on temporally ordered data leaks the future and inflates every number in the document.

Then the segment breakdown, with sample size next to every figure. Report the primary metrics for each segment you have committed to monitor: the dimensions along which the business is managed, geographies, product lines, new versus tenured customers, and any protected characteristics you are able to evaluate on. A model with strong aggregate performance and a segment where it performs no better than chance is a model with a defect, and the aggregate is designed to hide it. Attaching sample sizes is not pedantry: a segment with a hundred and fifty rows produces a metric with an interval wide enough to be uninformative, and reporting the point estimate alone invites a reader to conclude something the data cannot support.

Two further comparisons make the evaluation decision-grade rather than descriptive. A baseline — the current rule set, the previous model version, or the trivial predictor — because a metric without a baseline cannot answer whether shipping this is an improvement. And a calibration check if the score is consumed as a probability, since a model can rank well and still be systematically over-confident, and any downstream expected-value calculation depends on calibration rather than on ranking.

Known limitations, written as a deliverable

This section is where an experienced author is distinguishable from a template, because it takes judgement and it cannot be generated. It says where the model is known to be weak and what happens when it is.

Inputs it handles badly: the thin segments, the ranges outside training support, the categories that appear rarely. Conditions under which it should not be trusted: a regime change of the kind that occurred in the training period, a promotional event, a market condition absent from the data. The failure modes and their direction, since a model biased towards false positives has a different operational consequence from one biased towards false negatives, and the operations team needs to know which. Dependencies that can fail and the behaviour when they do — what the model receives if a feature service times out, and what the service returns if the model is unavailable. And any feedback loop the deployment creates, where the model's own decisions shape the data it will later be trained on.

Write these as statements about the world rather than as hedges. "Performance on merchants active for under thirty days is materially worse and those cases are routed to review" is a limitation. "Model performance may vary" is a disclaimer, which is a different thing and provides no protection to anyone.

The approval record

The last artefact is a record of a decision, and it needs four things a document alone does not provide: who reviewed it, what they reviewed against, what they decided, and when it must be looked at again.

Name the accountable owner, the reviewers with their remit — a technical reviewer who checked the evaluation, a risk or compliance reviewer, a business owner accepting the outcome — and record any conditions attached to the approval, such as a required monitoring threshold or a mandated canary period. Record the exact artefact approved, by version identifier, so that "the model that was approved" is unambiguous later. Approving "the fraud model" approves nothing, because it will be retrained next month.

Then set the re-review triggers, because a permanent approval is the mechanism by which governance decays. Time-based review is the weak form. The useful triggers are event-based: a retrain that changes features or training window, a threshold change, a new population or market, a monitoring breach, and any use outside the documented scope. Each of those should require the pack to be refreshed and the decision retaken.

Keep the burden proportionate by splitting the pack in two. The parts that are facts — dataset identifiers, metric tables, segment breakdowns, feature lists, training configuration — should be generated by the pipeline on every run, because hand-maintained numbers go stale by the second retrain and a stale number in a governance document is worse than an absent one. The parts that are judgement — intended use, out-of-scope use, limitations, the risk acceptance — are written by people and reviewed when the judgement could have changed. A model documentation practice that requires a human to retype metrics is one that will be abandoned quietly within a year.

The generated half keeps itself current; the written half is where the value is. If the pack cannot answer what this model must not be used for, and who accepted the risk on which version, it is a description rather than a control.