Opinion · An editorial recommendation
Documentation written by the expert is tested by the expert
The person who built a service cannot easily see what is missing from their own notes, because they supply the absent steps automatically while reading. That is why handover packs pass review and fail on the first real Monday.
A useful test is somebody else doing the work from the document, unaided, on something safe.
Run the test on an ordinary task
Pick a routine request the service receives weekly — a permission change, a scheduled job rerun, a certificate check — and ask a colleague to complete it using only the notes. Sit out of earshot and take notes on where they stop.
Each stopping point identifies something the receiving operator needs: an omitted step, unclear evidence or access that has not been arranged.
Keep credentials out and access processes in
A handover pack should reference the approved route to access rather than carry secrets. Pasting passwords into a shared document creates a second problem that outlives the first, and it removes any usable record of who used what.
Name the vault, the approval, and the person who can grant it. That is the durable version of the same information.
Name an owner and a review date
Instructions decay with every change to the service, so agree who updates them and when they are next read. A named owner and review date make maintenance explicit, but the instructions still need to be tested in use.
Repeat the test after any significant change. Allow enough time for a colleague to complete the task and record the gaps.
Make the test observable
For a fictional overnight import, the receiving operator should find the schedule, identify the most recent successful run and explain what they would do after a failure. If a rerun can duplicate records, the instructions must say how to establish whether it is safe. Use a test environment for actions that could change data.
The author can observe silently, but must interrupt if the agreed boundary is about to be crossed. Record the interruption as a missing instruction or safeguard. Leaving someone unaided should never mean allowing damage simply to prove the document was incomplete.
Agree what remains with the original team
At the end, separate completed checks from unresolved gaps. Name who supplies missing access, who fixes the runbook and when the receiving team will retest. Record any temporary support arrangement with its hours and escalation route.
Acceptance should include the service purpose, owners, access route, routine tasks, common failures, recovery instructions and known limitations. The recipient needs enough information to judge whether the service can be supported, not merely a shared folder containing a diagram.
Something needs correcting?
Get in touch to explain which claim needs attention and share the supporting source.