Documentation and model cards

Traditional model cards describe a model’s purpose, training, evaluation, and limitations. That remains valuable, especially for model providers. A deploying organization needs a broader system card or governance record because behavior also depends on:

• model provider, name, version, and release mode;
• system and developer instructions;
• retrieval sources and update frequency;
• input transformations, filters, and business rules;
• tools, permissions, and downstream actions;
• interface design and human-review steps;
• user groups, geography, language, and operating environment;
• monitoring, fallback, and incident procedures.

A provider card might say a model performs well on general question answering. It cannot prove that your support assistant follows your refund policy. Local documentation must connect component evidence to the intended use.

Start with a concise record that a reviewer can scan.

Identity and status: system ID, current version, lifecycle state, accountable owner, technical contact, approval date, next review date, and links to evidence.

Purpose and boundaries: the user need, intended users, decisions or actions supported, approved environments, prohibited uses, and explicit non-goals. “Customer support” is too broad; “draft answers to authenticated customers’ product-navigation questions for agent review” is testable.

System description: components, data flows, dependencies, model and prompt versions, retrieval sources, integrations, permissions, and human checkpoints. A diagram can help, but it must match production.

Data: sources, authority, sensitivity, quality constraints, retention, representativeness, and known gaps. Distinguish data used for training, retrieval, evaluation, live inputs, and logging.

Evaluation evidence: test-set scope, metrics, acceptance thresholds, subgroup results, qualitative review, red-team findings, date, and evaluator. Include failures and uncertainty, not only headline scores.

Limitations and controls: conditions where performance weakens, possible harms, prohibited inputs, guardrails, escalation triggers, monitoring signals, rollback path, and unresolved risks.

Decision history: approvals, conditions, exceptions, rejected proposals, significant changes, incidents, and retirement decisions. Each entry should identify the evidence version used.

Documentation loses value when it reads like marketing. “Best-in-class accuracy” is not actionable. State the task, dataset, metric, result, and boundary: “On 600 English billing questions sampled from March traffic, reviewers rated 91% of drafts policy-consistent; performance was 78% for cancellation disputes, so those requests are escalated.”

Record negative findings. A limitation hidden to make approval easier will return later as an incident. Distinguish a known limitation supported by evidence, an assumption not yet established, an open risk awaiting treatment or acceptance, a control currently reducing risk, and an unknown where evidence is insufficient. These labels stop approvers from treating plans as proven controls.

Do not paste every artifact into one enormous document. Maintain a readable top-level record linked to versioned evaluation reports, dataset descriptions, privacy reviews, threat models, approval records, dashboards, and incident reports.

Traceability means a reader can determine which model, prompt, data, and code produced an evaluation result. If the evaluation set changes, preserve the old result and create a new version. If a dashboard is mutable, store the time range and decision snapshot used for approval.

Sensitive documentation needs access control. A card should not expose personal data, security weaknesses, secret prompts, or exploitable thresholds to everyone. Provide different views when necessary: a public transparency notice, an internal operating record, and restricted technical evidence. Different access does not justify missing evidence.

A document written at launch and ignored is an archaeological artifact. Update it after a model, prompt, retrieval, data, tool, or policy change; expansion to new users or languages; a monitoring breach or incident; new regulation or vendor information; ownership transfer; and periodic review.

Assign each section an owner and source. Some fields can be generated from deployment metadata, but generated text still needs validation. Automation can report the deployed model version; it cannot decide whether the approved purpose remains appropriate.

Give the record to someone outside the delivery team. Ask: What does this system do? What may it not do? Which version is live? What are its top failure modes? What evidence justified release? Who can pause it? When must it be reviewed? If answers require private messages or oral history, the record is incomplete. If the document answers them but production differs, the system is out of control.