Why I Write the Handover Doc Before the Build

Why would anyone write the handover doc before building the automation?

Because writing it first forces every hard decision into the open before it gets expensive. Who owns the automation after launch? What happens when it fails? Which fields can it change? If I cannot answer those in a handover doc on day one, I am not ready to build, and the client is not ready to own it.

Most people write the handover document last. The build is done, the client is happy, and someone quickly writes up how things work so the project can close. That order is common, and it tends to produce docs that are rushed, incomplete, and sometimes wrong by the time anyone reads them.

So I flipped the order. Now the handover doc is the first artifact of an automation project, before a single workflow exists. Here is why, and what goes in it.

What goes into a handover doc written up front?

Six things: what the automation does in one paragraph, who owns it after launch, what systems it touches and with what permissions, what a failure looks like and who gets alerted, how to pause it safely, and what is explicitly out of scope. Every section starts as a question I need the client to answer.

The one-paragraph description sounds easy and rarely is. If I cannot describe the automation in plain words to someone outside the project, the scope is still fuzzy. Writing that paragraph first can surface a disagreement nobody knew existed. Sales might expect leads to be routed by territory while marketing assumes they are routed by source.

The ownership section names a person, not a team. "Marketing ops" is not an owner. "Priya, marketing ops lead" is. If there is no name to write, that is the first problem to solve, and it is better to solve it before the build than after.

How does it change the build itself?

It turns the build into filling in a plan instead of discovering one. When the doc already says which fields the automation may write, I build exactly those permissions. When it says what failure looks like, I build that alert first. The doc acts like a spec that the client has already read and agreed to.

It also makes scope creep visible. When a new request comes in mid-build, I check it against the out-of-scope section. Sometimes it is a reasonable addition, and the client and I update the doc together. Sometimes it is a separate project. Either way, the conversation happens with the document on the table, not from memory.

This works well with fixed-fee pricing, which is how I price most projects. Most of my projects land between $1,000 and $10,000, fixed. A fixed fee only stays fair if scope is clear. The handover doc is where scope becomes clear enough to price honestly.

Does writing it first slow the project down?

It adds a short planning step and removes a lot of rework. The first draft is short. Answering its questions with the client is usually one conversation. In exchange, I avoid building the wrong thing, rebuilding permissions late, or discovering after launch that nobody knows who owns it.

The slowest part is usually waiting for answers, not writing. A client who cannot name an owner in the first week will not magically find one at launch. Better to find that out early, when there is still time to help them decide.

The doc also saves time for the client's team. They read a short document before the build and know what is coming. There are fewer surprises, fewer "wait, it does what?" moments, and a smoother launch.

What does the failure section force you to decide?

It forces you to define failure before you can see it. What counts as broken: a missed lead, a duplicate record, a wrong owner? Who finds out, how fast, and through which channel? What should they do in the first ten minutes? Those answers shape the build more than any happy path does.

This connects to a habit I wrote about in why I write the failure alert before the happy path. The handover doc is where that alert gets its definition. Without the doc, alerts get added at the end, with vague messages that nobody acts on.

Defining failure up front also protects the client. An automation that fails quietly can do damage for weeks. One that fails loudly, to a named person, with a clear first step, gets fixed the same day.

How do you handle clients who just want it built?

I explain that the doc is part of the build, not extra work, and keep it short enough that it never feels like a burden. The questions make the case on their own. They are the same questions a client would face later, under pressure, if the automation broke without a plan.

If a client still wants speed, and a document sounds like paperwork, I keep the first version to two pages and fill in what I can myself. The client only answers the questions I cannot, which keeps their part small.

If a client refuses to name an owner or define failure at all, that tells me something useful about the project. An automation without an owner will decay. I would rather have that conversation before I take the project than after I deliver it.

What happens to the doc after launch?

It becomes the living reference for the automation. I update it during the build whenever a decision changes, and hand over the final version at launch. The client's team keeps it next to the automation, and anyone who touches the system later reads it first. A doc written early has been tested by the whole project.

That last point matters. A handover doc written at the end has never been used. A doc written at the start has been read, questioned, and corrected for weeks. By launch day it reflects reality, because reality kept correcting it.

For the mechanics of actually handing a system over to a client's team, I covered the steps in how to hand over an automation to a client's team.

Does this apply to large automations as well as small ones?

Yes, and the larger the system, the more it pays off. I run automations in production for clients like Ajust, built on Airtable and WhaleSync, which has delivered more than 25,000 cases and helped more than 400,000 people. Systems at that scale need clear ownership, permissions, and failure handling from the start.

Smaller projects benefit too. A single Zapier workflow that moves form leads into HubSpot still touches customer data and still needs an owner. I also run CRM automations for Kismet Health on HubSpot via Zapier. Even a small workflow deserves a short doc that says who owns it and what happens when it breaks.

The doc scales with the project. For a small automation it might be one page. For a large one it might be ten. The six questions stay the same.

What would I tell someone starting their first automation project?

Write the handover doc first, even if it is rough. Answer the six questions with the person who will own the automation. If anything stays blank, treat it as a blocker, not a detail. You will build faster, scope more honestly, and hand over something the client can actually run.

It feels backwards at first. Writing documentation for something that does not exist yet seems like wasted effort. In practice, the doc is a decision record. You are not documenting the build. You are documenting the agreements the build depends on.

After 100+ projects for 25+ clients over 6+ years, this is one of the few habits I would keep if I had to drop everything else. Clear agreements up front make every later step easier. For more on documenting automations for clients, see how to document automation handoffs for clients.

What should you do next?

If you have an automation project starting soon, open a blank document and write the six section headings: what it does, owner, systems and permissions, failure and alerts, how to pause, and out of scope. Fill in what you know. Send the blanks to the client as questions before you build anything.

If you already have automations running without a doc like this, write one for the most important workflow this week. You will likely discover at least one unanswered question, and it is far better to find it now than during an outage.

If you want help planning an automation project this way, or want a second opinion on one already in flight, reach out. I build websites and the automations behind them for lead generation, and this is how I like to start projects. Let's chat.