The Handoffs Were the Documentation

An enterprise implementation used to be three jobs.

Someone gathered requirements. Someone built against them. Someone else operated the result once it was live. In the larger programs these were three different people in two different companies, and the boundaries between them were where the documents lived: a requirements specification, a technical design, a runbook and a handover. The documents existed because the work had to cross an organizational line, and things that cross lines have to be written down.

The forward deployed role collapses all three into one person. They elicit the requirement, build the thing, and carry the pager when it misbehaves at two in the morning. This is usually described as an efficiency — fewer handoffs, less telephone-game distortion, faster loops — and it is that. But it has a consequence that gets less attention, which is that the documents go away with the boundaries that produced them.

What the seams were actually for

It's worth being precise about why those artifacts existed, because efficiency wasn't the reason. They existed because information had to survive a transfer between people who did not share context.

That gave them a second function almost by accident. A manager who had never sat in the finance workshop could read the requirements document. A director who had never written a line of the integration could read the design. The artifacts made the work legible to people who were not doing it — which is, more or less, the definition of supervision.

Remove the boundaries and you remove the artifacts, and the legibility goes with them. Not because anyone decided to stop documenting, but because nobody is on the receiving end of a document anymore. The engineer who elicited the requirement is the same one building against it. Writing it down for themselves is overhead with no reader.

The owner-builder case

Building codes assume a division of labor. An architect draws, a contractor builds, and an inspector who works for neither one signs off at defined stages. The drawings and the permits and the inspection records are the artifacts at those seams, and the reason the system works is not that any individual is more careful but that the person checking is not the person who did the work.

Most jurisdictions also allow an owner-builder exemption, where a homeowner can design, build, and certify their own house. Some of those houses are excellent — often better than the contracted ones, because the person building it intends to live there. But the failure mode is specific and well known: nothing is wrong at any single point, and yet nobody outside the project can tell whether it is going well until something is uncovered years later. The inspection didn't fail. It was never a separate act.

That's the shape of the management problem with a collapsed role. It isn't that the work is worse. It's that from the outside, good and bad look identical for much longer.

What this does to managing it

A manager of an old-style implementation could review artifacts. Read the requirements, read the design, walk the test plan. You could form a real opinion without having done the work yourself.

A manager of a collapsed role can't do that, and I think the common responses are all worse than they look.

Managing by outcome is the honest one — did the deployment succeed, did the customer renew — but the feedback arrives in quarters, and by the time it arrives the same mistakes have been made four more times in four more accounts.

Managing by proxy metrics is the tempting one, and it quietly rebuilds the old incentive. Count engagements, count hours, count tickets closed, and within a year you have a services organization inside a product company wearing a different name.

Managing by asking is the one that actually works, and it has a prerequisite that people don't like saying out loud. The questions that reveal whether a deployment is going well are specific and unglamorous — what did the customer's data look like when you first pulled it, what have you built that you'd be embarrassed to see three more times, which of your assumptions has already failed. Those questions are obvious to someone who has recently done the work and nearly impossible to generate otherwise. Not because managers who haven't done it are less capable, but because the questions come from having been surprised in that particular way before.

Which makes hands-on experience less a matter of credibility with the team, the usual argument for it, and more a matter of calibration. You are the instrument. There isn't a document standing in for one.

The artifact that does survive

One thing does get written down, and it's the one worth reviewing.

In a system built on models rather than rules, somebody has to decide what the right answer is on the cases where reasonable people disagree. Those decisions get written down as an evaluation set: a list of real inputs taken from the customer's own data, each paired with the answer someone has committed to as correct, with the awkward cases deliberately over-represented. It runs. You can point it at a new version of the system and get a number back.

That record is the closest thing this era has to a requirements document, and in one way it's a better one. A requirements document states intentions. An evaluation set states commitments — this input, this answer, decided by this person, on this date. You cannot put a hard case in it without settling the hard case, which is exactly what the workshops used to defer.

If I could look at only one thing to judge how a deployment was going, it would be that — not the code, not the status report. It's the subject of the next essay in this series, so I'll leave it there.

Three things this argument doesn't settle

It doesn't scale. A manager who has done the work can calibrate against three or four engineers in domains they know. At thirty engineers across a dozen industries, that breaks. Nobody has a good answer to this yet.

It's easily abused. The claim I've just made — that a manager should have done the work — is the standard cover for a manager who overrules engineers on technical calls because they did the job themselves five years ago. That isn't the argument. Having done it tells you which questions to ask; it doesn't make you the right person to answer them, and the answers have moved since you were last in the field. From the outside those two managers look identical. To the engineer they feel nothing alike.

And it might be wrong. Think about how a sales team gets managed. Nobody reads a document describing what the salesperson actually said in the room. There is no artifact between the first call and the closed deal, and a manager who wasn't there has no way to inspect the work itself. That is the same condition I've been describing as a problem — and in sales nobody treats it as one. The function is managed on outcomes and it works. So maybe the missing documents were never the real issue, and deployment engineering simply hasn't invented its version of the pipeline review yet. I doubt it, because a bad deployment shows up in the product rather than in a quarter's number. But I could be wrong about that.

The point

Collapsing the role was the right call. Fewer handoffs is better, and the distortion they introduced was real.

But the paper trail went with them, and that paper trail was how people who weren't there could tell whether the work was any good. Companies book the efficiency immediately. They find out about the other half later — usually when they try to grow the team from three to thirty and realize they can't say which of the three were good at it.