A regional legal-services firm needed to train new hires on a state court e-filing system. That sentence sounds ordinary until you notice what it rules out. Every action in that system is a real submission to a real court: irreversible, timestamped, occasionally billable, and attached to someone’s actual case. There is no sandbox. There is no practice mode. There is no undo.
So the training method was the one every office in this position falls back on. Watch someone competent do it a few times. Then do it yourself, live, with that person standing behind you. Everyone learns eventually, because everyone has to. The cost is spread thin enough to be invisible: a senior person’s afternoon, a nervous new hire, and the occasional expensive mistake that gets caught late.
What the task actually was
The obvious framing is “clone the interface.” That framing is wrong, and following it produces something that demos well and teaches nothing.
The real task was to build somewhere a person could be wrong — repeatedly, cheaply, in the specific ways this system invites you to be wrong — and to come out the other side with evidence of whether they had got it right. Not a tour. A place to fail on purpose.
Those are different products. A tour optimises for looking like the original. A practice environment optimises for the moments where judgement happens, and is allowed to be honest about everything else.
Fidelity is a trap
The instinct is to reproduce every screen exactly. Resist it. Perfect fidelity has two costs and one hidden failure.
The costs are obvious: it is enormous work, and it goes stale the first time the real system ships a change. The hidden failure is worse. A mock that pretends to be the real thing teaches superstition. Trainees memorise the sequence of clicks rather than the reasoning, and when the real system differs — as it always does, in some corner nobody mocked — they have no way to tell whether they are looking at a genuine difference or a thing they misremembered.
So I inverted the rule. Reproduce the moments where people make expensive mistakes with real care. Simplify everything else deliberately — and then document every simplification in the training materials, by name, as a divergence.
That single decision does more pedagogical work than any amount of pixel matching. A trainee who has read the divergence list knows where the map stops matching the territory. A trainee who has been told “this is exactly like the real one” has been handed a false confidence that will fail them at the worst possible moment.
Some divergences worth defending
- Outcomes are randomised. Submit a filing and the clerk’s response is rolled, not earned. If practice always ended in success, trainees would learn to expect success — and the whole point is rehearsing the day it does not come.
- Coaching is labelled as coaching. The environment offers hints the real system never would. Every one of them is marked as trainer guidance rather than system behaviour, because a hint mistaken for a rule becomes folklore within a month.
- Some paths are visibly disabled. Not hidden — disabled and greyed. A trainee should be able to see the edge of the environment rather than discover it by walking off it.
- Reference data is abbreviated. Enough breadth to exercise the judgement, not a synchronised copy of a dataset that would be wrong within a quarter anyway.
No backend, on purpose
One self-contained HTML file. No server, no accounts, no database, no network calls at all. It opens by double-clicking it.
This was a constraint before it was a design choice, and it is the reason the thing exists. A training tool that needs hosting needs a budget conversation. A tool that needs accounts needs someone to administer them. A tool that sends anything anywhere needs a data-handling review — entirely reasonably, in a legal setting. Each of those is a place where a useful internal project quietly dies waiting for approval.
Removing the backend removed all three conversations. Everything a trainee does stays in their own browser storage. Unfinished work autosaves and resumes, so a closed laptop is not a lost session. When an assessor needs to see what somebody did, the trainee exports a bundle and hands it over; the assessor’s copy imports it additively, skips duplicates, and refuses a file of the wrong shape without touching what it already holds.
That is a sync protocol, written out longhand, with humans as the transport layer. It is not elegant. It shipped in days instead of never, which is the only comparison that matters.
Assessment is the hard half
Building a wizard is a known problem. Screens, state, validation, a back button that does not lose your work. It is work, but it is the kind of work where you know when you are done.
The genuinely hard problem is this: two different assessors, looking at the same trainee attempt on different days, should reach the same verdict. If they do not, the assessment is theatre. It feels rigorous, it produces a score, and the score means nothing.
Two decisions carry most of the weight there.
First, correctness is computed at the moment of submission, not later. The checks run once, against the state as it was, and the result is stored. An assessor opening the record next week reads a verdict; they do not re-derive one from live application logic that may have changed since. Re-deriving is how two assessors get two answers.
Second, what gets stored is a flattened snapshot. Not identifiers to look up, but the resolved, human-readable values as they stood: the names, the selections, the list of what was attached. The record is legible on its own terms, years after the code that produced it has moved on. A record that depends on the current build to be readable is not a record, it is a cache.
One nuance that took a conversation to settle: not every flagged thing is a failure. There is a shortcut in the real workflow that looks like a mistake but is entirely legitimate when the information was verified another way. The environment surfaces it to the assessor and pointedly does not count it against the trainee. Marking a defensible choice as wrong teaches people to work around the assessment rather than do the job well — and they will, immediately, because everyone does.
What I could verify, and what I could not
The flows are covered by automated suites running headless: full paths end to end, the interstitial screens that block progress under specific conditions, editing a record already entered, the validation that accepts a valid combination and rejects an invalid one, autosave and cross-session resume, and a three-machine export/import merge where re-importing the same bundle twice changes nothing the second time.
Four things those suites cannot attest, and I would rather say so than let a green run imply otherwise: the browser’s leave-page warning, the real file picker, an actual download landing on disk, and the print dialog. A headless environment does not have them. Anyone claiming test coverage over those is describing their mock, not the browser.
That gap is not just declared, it is designed around. The autosave-and-resume path exists because the persistence guarantee could not be allowed to rest on the one behaviour I cannot prove. If the leave-page warning never fires, the work is still there when they come back. The unverifiable thing is a convenience, not a load-bearing wall.
The part that generalises
Most internal training is built by whoever is most annoyed by the current situation, in a hurry, and it optimises for looking complete. The version that actually works optimises for something less flattering: giving people a cheap place to be wrong, being honest about where the model stops, and producing a record that a second person can read the same way you did.
None of that is technically difficult. It is just a different question than the one you get asked, which is almost always “can you make a copy of this.”
Leave a Reply