Skip to content
Français

Documentation

  • Lesson 15
  • 30 min
  • Module 5: Controls, documentation and evidence

Where we are

In the last lesson, we gave each policy line a control and the record that proves it. Many of those records are documents: a card that says what a system is, a decision, a list of changes. A document that nobody updates soon says something false. In this lesson, we see which documents an AI system needs and how they stay current, like a car’s service book.

What you will be able to do

Keep the few documents that an AI system needs, so that anyone can see what it is, why it is allowed and what changed. Keep them true by writing them as part of the work, not afterwards.

Before you startWhat to know and to have readyAbout 30 minutes

What you need to know

What you need

A used car comes with a few papers. The registration says what the car is: the model, the engine, the owner. The service book has a stamp for each service, with the date, the garage and what was done. A letter from the maker may say: “Bring the car in: we must replace a part.”

A buyer reads the service book first. If the last stamp is three years old, the book says nothing about the car today. A good service book stays current for a simple reason. The garage stamps it during the service, as part of the job. Nobody writes the history later from memory.

The problem: a card that says something false

Section titled “The problem: a card that says something false”

Farida reads the card of the document assistant, S3, next to the platform registry’s record of it. Both are constructed for this course. They disagree.

Field The card says The registry says
Data it uses internal, staff-only and the partner shop’s documents internal, staff-only
Last review at launch overdue by 2 months

In the board’s first quarter, Larkfield approved three changes to the document assistant: two at the board and one on the fast path (constructed). It got two new product manuals and the new returns policy, and it now answers the partner shop’s new staff. Neither the card nor the registry shows any of these changes.

Nothing went wrong yet. But the next owner, or an auditor, would read a card that is wrong about the data and about the changes. If a partner shop’s document leaked, nobody could say when that data was added, or who decided it.

The idea: four documents, each with one job

Section titled “The idea: four documents, each with one job”

An AI system needs few documents. Each one answers one question for one group of readers.

  • A system card says what the system is now: purpose, owners, tier, data, model, what it may do alone, its last evaluation and its limits. Staff, the board, an auditor and the next owner read it.
  • Model information from a vendor says which model is inside, what it does badly and how the vendor tells you before it changes. Some vendors call it a model card. The system’s owner and the risk lead read it.
  • A decision record says why the system may do what it does: who decided, which options they considered, the evidence, the conditions and what would change the decision. The board and an auditor read it.
  • A change log has one line per change: the date, what changed, who approved it and a link to the evidence. People who review an incident read it first.
Four documents, each with its question, readers and when it is written. System card: what is it now? Read by staff, the board, an auditor and the next owner; updated in each change. Model information from a vendor: what model is inside and what does it do badly? Read by the owner and the risk lead; asked for at the vendor check and when the vendor changes the model. Decision record: why may it do this? Read by the board and an auditor; written when the decision is made. Change log: what changed, when and who approved it? Read by incident reviewers and an auditor; one line per change.
Four documents and their jobs. Each one is written at a moment in the work, not on a documentation day.
Text description of the diagram

The diagram shows four documents side by side. The system card answers “What is it now?”. Staff, the board, an auditor and the next owner read it, and it is updated in each change. The model information from a vendor answers “Which model is inside, and what does it do badly?”. The owner and the risk lead read it. It is asked for at the vendor check, and again when the vendor changes the model. The decision record answers “Why may it do this?”. The board and an auditor read it, and it is written when the decision is made. The change log answers “What changed, when, and who approved it?”. Incident reviewers and an auditor read it. It gets one line per change.

How many of these does a system need? The risk tier says. A low-tier system needs its inventory row and a named owner, and no card. Medium and high systems need a system card kept current, a change log, and the evaluation result of each release in a decision record. So the document assistant, which is low, could live with its inventory row. Larkfield chose to keep its card. If it keeps one, the card must be true.

A tiny example: the document assistant’s card, field by field

Section titled “A tiny example: the document assistant’s card, field by field”

Here is the S3 card rewritten with the template. Each value shows where it comes from, so that the next update knows where to look.

Field Value Where it comes from
Purpose answers staff questions from documents, with citations the old card
Not for answers sent to customers that nobody has read; legal advice (constructed) Mei, the owner
Owners Mei (accountable); Mei’s data team (technical) the old card and the registry
Tier low (5), set with the course’s method; the registry also says low the risk-tier table
Data internal, staff-only, the partner shop’s documents the old card; the registry must be corrected
What it may do alone answers a person, who decides the registry
Evaluation 41 held-out questions, 87.8% right; 430 attempts to read the other shop’s documents, 0 leaks recorded in Portfolio Capstone: Build, Evaluate and Ship an AI Product
Links decision records of the three changes; the change log the board log
Next review overdue: set a date this month the registry’s review date

Writing the card took three findings: the registry’s data classes are incomplete, the review is late and the changes have no trace. Here is the change log that should have existed (constructed from the board log):

Request Change Path Approved by
R-03 two new product manuals board, 21 working days the board
R-07 answers for the partner shop’s new staff fast path, 2 working days Mei and Farida
R-09 the new returns policy board, 17 working days the board

And the decision record for R-07 fits on half a page. Decision: the document assistant may answer the partner shop’s new staff. Decided by: Mei and Farida, on the fast path. Evidence: the 430 recorded probes with 0 leaks. Condition: each shop sees only its own documents; Mei checks it after each change. What would change it: one leak in a test, or a complaint from the partner shop.

For a bought AI feature, the vendor holds the model information. Larkfield cannot write it. It can only ask. Question 8 of the vendor questionnaire asks which model is used, what it does badly, and whether the vendor gives notice before a change. The two answers that Larkfield received (constructed; the vendors are made up for this course):

  • TicketHarbor: “We use leading AI models.” This names nothing and promises nothing.
  • MinuteMoss: “Notes are written by a large language model; they can contain mistakes.” This gives a limit, but no model name and no notice of changes.

So the system cards of S6 and S7 cannot fill the “model” field yet. Write that gap on the card, with the date of the question, instead of leaving the field empty.

The EU AI Act gives providers of general-purpose AI models duties of their own (Regulation (EU) 2024/1689, Article 53, official source, checked 22 October 2026). What a vendor must give to a company like Larkfield, and in which case, is a question for the lawyer. For governance, the rule is simpler: ask, and record the answer or its absence.

Documentation fails when it is a separate job. Larkfield uses four habits, so that every document is written at a moment that already exists in the work.

One change, five records, all in the same change. A change request, such as R-07, leads to a decision on the fast path or at the board. The decision writes a decision record. The change itself adds one line to the change log, updates the system card's fields and updates the registry record, which feeds the owner, tier and review date of the card. The change is done only when all of them say the same thing. A dotted grey box says: not a separate documentation day.
Documents written in the same change. The change is not done until the card, the log and the registry agree.
Text description of the diagram

The diagram shows one change request, for example R-07, going to a decision on the fast path or at the board. The decision writes a decision record. The change itself then adds one line to the change log, and it updates the system card and the registry record. The registry gives the card its owner, tier and review date, so nobody types them twice. The change is done only when all of these say the same thing. A dotted grey box says: “not a separate documentation day”.

  1. Write the decision record in the meeting. The person who decides writes or approves it before the meeting ends.
  2. Update in the same change. A change to the system includes its change-log line and the card’s fields. The change is not done until the card says it.
  3. Do not type twice. The registry already holds the owner, the tier, the tools and the review date. The card points to them. Link the evaluation record; do not copy its numbers into three places.
  4. Let the review date warn you. The registry showed that the document assistant was two months late. A list of all review dates makes late cards visible.

What does it cost? The first card takes some work, because it finds the gaps. After that, each change adds a few lines. A documentation day costs more, and it produces documents that are true for one day.

Discuss: “The vendor’s documents cover the bought tools”

Section titled “Discuss: “The vendor’s documents cover the bought tools””

Farida asks for a card for each medium and high system.

  • Omar: “Cards slow us down. The registry already knows everything.”
  • Tomás: “For the bought tools, the vendor’s documents are enough. They built it.”
  • Mei: “The registry did not know about the partner shop’s documents. The card did.”
  • Sam: “Who updates the card when something changes?”

Before you read on, answer these:

  1. What does the registry know, and what does it not know?
  2. Can the vendor’s documents replace Larkfield’s card for the reply suggester?
  3. Who should update a card?

The course’s answer. The registry knows what it is told: owner, tier, tools, budget and review date. It does not know the purpose limits, the people affected or the reasons for decisions. So the card uses the registry for its fields and adds the rest. The vendor’s documents describe the vendor’s product. They cannot say who at Larkfield owns the feature, which data Larkfield sends or what staff may do with it. Larkfield’s card can link to them. Today, TicketHarbor’s answer names no model at all. The accountable owner updates the card, as part of each change that they approve.

What would change the answer: suppose the registry stored every field of the card, with a review date. Then the card could be a page that the registry prints, and nobody would write it by hand.

Common mistake

A card that is true for one day

Symptom: every system has a well-written card, and the cards all have the same date. Changes since then are not on them.

Cause: the cards were written for an audit or a launch, as a separate job. No step in a change updates them.

Fix: add “card and change log updated” to the steps of every change, and check it when the change is approved. Compare each card with the registry once a quarter, and treat each difference as a finding.

Guided practice: the triage service’s card

Section titled “Guided practice: the triage service’s card”

S1, the ticket triage service, is high tier, so it needs a card, a change log and a decision record for each release.

  1. Open the system card template and the card S1.

  2. Fill in the purpose, the owners and the data from the S1 card: Grace is accountable and Amira is technical owner.

  3. Fill in the tier: high (10) with the course’s method. Add: “the registry says low: to be corrected”.

  4. Fill in “what it may do alone”: it routes every ticket alone; agents read and send the drafts.

  5. Fill in the evaluation: prompt version 2 on 98 held-out tickets, 94 with both decisions right. This is recorded in Evaluating and Testing AI Systems.

  6. Fill in the known failures: in the “last week”, 10 tickets that needed a person reached nobody. This is recorded in MLOps and LLMOps: Operating AI in Production; the situation is constructed.

  7. Write one change-log line for that release: version 3 to every customer, release gate passed 0 of 6, approved by: nobody recorded.

    Check: the change-log line already shows a finding. A release with no approver and a failed gate reached every customer.

Your turn: complete the card and one decision record

Section titled “Your turn: complete the card and one decision record”

Finish the S1 card: “not for”, monitoring and pause conditions, the impact assessment and the next review. Then write a decision record for one vendor decision you made in Module 4, for TicketHarbor or MinuteMoss.

Check your work
  • Next review: a high-tier system is reviewed every 3 months. The card’s last review was a post-incident review in month 2.
  • Impact assessment: needed, signed by the accountable owner and reviewed by the board, because S1 is high and affects every customer who writes.
  • Not for: for example, sending replies without an agent, or deciding refunds.
  • Decision record: it names who decided and the options, including “keep off”. It links the vendor answers used as evidence and gives each condition an owner. It says what would change the decision, for example the vendor naming its model provider.

Check your understanding

The document assistant is low tier. Does it need a system card? What must be true if Larkfield keeps one anyway?

Show the answer

No: a low-tier system needs its inventory row with a named owner, and no card. A card is required from the medium tier. If Larkfield keeps a card for a low-tier system, the card must be true. A wrong card is worse than none, because people act on it. Today the S3 card is right about the partner shop’s documents, but its review date and its changes are missing.

Check your understanding

Match each question to the document that answers it: (a) Why may the workflow propose refunds? (b) When did the triage prompt change, and who approved it? (c) Which model does the meeting-notes tool use?

Show the answer

(a) the decision record: who decided, the options, the evidence and the conditions. (b) the change log: one line per change, with the date and the approver. (c) the model information from the vendor. MinuteMoss’s answer does not name the model yet, so the card records that gap.

Check your understanding

Omar suggests a 'documentation week' before each audit. Why does this fail, and what should Larkfield do instead?

Show the answer

Documents written in one week are true for that week, and they are written for the audit, not by the work. Changes after it are not on them. Instead, update the card and the change log in the same change, and write the decision record when the decision is made. Take fields such as owner, tier and review date from the registry.

Recap

  • A system card says what a system is now; model information from the vendor says what is inside; a decision record says why it is allowed; a change log says what changed and who approved it.
  • The tier sets how many documents a system needs. Low needs an inventory row; medium and high need a card, a change log and decision records.
  • Keep them current by writing them in the work: the decision record in the meeting, the card and the log in the same change, the registry’s fields linked, not typed twice.
  • A card that disagrees with the registry is a finding, not a typing error.

You can now keep the documents that describe each system. But an auditor does not accept a description: they ask for proof that the control worked, for a period they choose. Next, you answer an auditor’s requests from the evidence pack and decide which evidence is old, missing or not enough.

Next: Evidence and audits