Write your deploy down, then watch somebody else follow it

Before you start

An hour, split into two sittings. A deploy that’s safe to do today, ideally to staging.

And one other person. They don’t have to be technical. Not being technical is arguably better, because they can’t paper over a gap with a good guess.

Deploy once, and write down what you did

Not what you’d say the process is. What you actually did, while you’re doing it.

Do a real deploy and narrate it into a document as you go. Every command, every click, every wait. If you open a dashboard to check something, that’s a step. If you wait for a green tick before the next thing, that’s a step, and so is what the tick looks like.

Write it in order, numbered, with no prose around it. You’re making a list somebody can follow, not an explanation of how deployment works.

Put the answers next to the questions

Read it back and look for anything a stranger would have to ask you.

Where is the repository? Which branch? What is the URL of the thing they’ll log into, and what is the account called? Which of the four similarly named environments is production? How long should the slow bit take before something is wrong?

Fill each of those in on the page. The test is that no step requires a piece of knowledge that only exists in your head, and right now nearly all of them do.

Don’t polish the writing. Nobody is grading prose here.

Hand it over and say nothing

Sit them down, give them the document, and let them deploy.

Say nothing. This is the whole guide and it is much harder than it sounds. You will want to help within about ninety seconds, because watching someone hesitate over something obvious is genuinely uncomfortable. Sit on your hands.

Write down every place they pause, ask, guess, or go the wrong way. Don’t correct in the moment. Note it and let them keep going.

The only reason to speak is if they’re about to do something destructive you can’t undo. That’s why this is better on staging.

Fix the document where they stopped

Every pause is a missing step or an ambiguous one. That’s your list, and it’s a better list than anything you’d have produced by re-reading it yourself.

Rewrite those parts using their words rather than yours. If they called it “the deploy button” and you called it “triggering the workflow,” they’re right, because the document is for them.

Cut anything they didn’t need. Documents that survive are short.

Have them do it again, alone

Same person, same document, a few days later. You’re not in the room.

If they can complete it without contacting you, the document works and your deploy is no longer a single point of failure. That’s the outcome.

If they can’t, that’s still a result. Fix the specific place it broke and run it once more. Two rounds is usually enough. If a third is needed, the process itself is probably too complicated, and the honest fix is to simplify the deploy rather than to write more words about it.

Put it where it will be found

A document nobody can locate in a crisis is a document that doesn’t exist.

Put it wherever your team already looks, not somewhere new and tidy. Link it from the repository’s README, since that’s where somebody will start. Put the date on it and the name of the person who last ran it successfully.

Then set a reminder to run the test again in six months, ideally with a different person. Deploys drift, and a runbook nobody has executed in a year is a document with unknown accuracy.

A boundary worth knowing about

This tests the normal path. It says nothing about the bad day.

Deploying works. Deploying when the build fails halfway, or when the migration is partly applied, or when you need to get back to the previous version in a hurry, are separate procedures that this exercise doesn’t touch. They’re also the ones you’ll need under pressure. Worth writing eventually, and much harder to rehearse, because you have to manufacture the failure first.

The other edge: the person who tested it now knows how to deploy, which was the point, and that’s also a decision about access. Somebody who can follow the runbook can follow it on a Friday night when you’d rather they didn’t. Decide deliberately who holds that, rather than discovering you decided it by accident.

If you have staff

Rotate who gets tested. The second person makes the document better than the first did, and after three you have something genuinely robust rather than something one specific colleague can read.

Make it part of onboarding. A new person running the deploy in their first fortnight, from the document, with nobody helping, is the cheapest and most honest documentation test that exists. They will find things nobody else can see, once, and then they’ll lose that ability forever.

The short version

1. Do a real deploy and write down every command, click and wait as you go
2. Fill in everything a stranger would have to ask: URLs, branch, account names, how long the slow bit takes
3. Hand it over and say nothing. Note every pause, don’t correct in the moment
4. Rewrite the parts where they stopped, in their words. Cut what they didn’t need
5. Have them do it again days later with you out of the room
6. Store it where they’d look, date it, and retest in six months with somebody else

Sources

This one is method rather than tooling, so there is nothing product-specific to cite and the guide names no platform on purpose. The evidence it produces is your own: a document somebody else used successfully while you sat there saying nothing.

Written August 2026. Nothing here depends on a particular tool or version, so it should age well. What ages is your deploy process, which is why step 6 sets a date to run this again.