Vision Field Notes

Handover Documentation for a Computer Vision System

The model works, the client is happy, the project ends. Six months later the site moves two cameras, alerts double, and the person who now owns the system opens a folder called final with three model files and no explanation. They cannot tell which model is running, how it was trained, or what the thresholds mean. Either they call you, or the system gets switched off.

A vision system is not finished when it works. It is finished when someone else can keep it working. This article lists what a good handover contains and how to make it usable for the person who receives it.

Who will read it

Usually not a computer vision engineer. More often a site IT person, a developer on the client's team, or a successor contractor. Write for someone technical but new to the project, who needs to answer practical questions quickly:

Organise the documentation around those questions, not around how you built it.

Three columns. The first lists the four questions a successor arrives with: is it running, this alert looks wrong where do I look, a camera was replaced what do I change, and which model is live and how was it trained. The second shows what they usually get: a folder called final containing best.pt, best_v2.pt, best_v2_FINAL.pt, config.yaml and notes.txt, with question marks beside the files that answer nothing. The third shows what to leave instead: a handover folder with a numbered system overview, runbook, camera and zone guide and retraining guide, plus models, config and data subfolders where the live model is dated and paired with its own notes file.
The left column is what arrives six months after you leave. The right column is the only thing that answers it without a phone call.

The middle column is not a strawman; it is what most projects actually end with. Three model files with no way to tell which is running, and a notes.txt written for the person who already knows.

The documents

1. System overview (one or two pages)

What the system does, in plain terms, and a diagram of the parts: cameras, the machine that runs analytics, where alerts go, where data is stored. Include the purpose and the limits agreed during the project: "detects people in the loading bay zone on cameras 3 and 7; not designed for the yard at night". Limits written down protect both sides later.

2. Operations runbook

The practical part, and the one that will be read most:

Write each procedure as numbered steps, and test it by having someone else follow it once.

3. Configuration reference

Every setting that affects behaviour, per camera: stream URL format (not passwords), zones, thresholds, schedules, cooldowns, model version. Ideally this is the configuration file itself plus a short explanation of each field. Managing Per-Camera Configuration at Scale covers how to structure it so it can be handed over.

4. Model card

One page per deployed model:

5. Retraining guide

How to reproduce the model and train a new one: where the data is, the annotation guide, the training command and configuration, the environment, how to evaluate against the test set, and how to export and deploy. Versioning Datasets and Models Together describes the records that make this possible.

Be honest about effort. "Retraining with new data takes about a day of compute plus labelling time" sets better expectations than "just run train.py".

6. Data and privacy notes

What footage and images are stored, where, for how long, who has access, and how deletion works, including training data and backups. This is often what an auditor or a new data protection officer asks for first. See Privacy and Ethics in Camera Analytics.

The files

Documentation without the artefacts is not a handover. Deliver:

Hand over credentials through the client's own password management process, never in the documentation itself.

Make it usable

Do a live handover

Schedule a session where the client's person runs through the runbook themselves while you watch: restart the service, find a log, change a threshold on a test camera, roll back a model. Every place they get stuck is a gap in the document. Fix it the same day.

If the contract includes a support period after handover, say what it covers and when it ends, in writing. Freelancing in Computer Vision covers how to scope that.

Checklist

Next steps: Writing a Results Report a Non-Technical Client Will Read and Agreeing a Measurable Target with a Client.