You cannot migrate what you cannot describe, and most integration estates have never been described — the schema says what a message looks like, not what happens if it arrives late, malformed, or twice. Documentation is now appearing as a funded, staffed workstream on real modernization programmes, which is the right instinct badly executed most of the time. The method that works: start from observed traffic rather than the admin console, capture four layers per flow (what exists, what it does, why it does it that way, who notices when it stops), and produce a one-page-per-flow artifact with a fixed shape rather than a wiki nobody opens twice.
Something worth noticing appeared on a job board this month: a nine-month contract, five days a week onsite, for a senior technical writer attached to an integration modernization programme.
Read that as a signal rather than a vacancy. An organisation has looked at moving its integration estate, concluded that the blocker is not the destination platform, and funded a person for most of a year to answer the question what does the current system actually do.
That instinct is right, and it usually gets executed badly. What follows is what the workstream should produce, in what order, and how to know when it is finished.
01 / The real gap
“Undocumented” is four different problems
Teams say an estate is undocumented as though it were one condition. It is four, they fail differently, and only the first one is usually addressed.
What exists
The inventory: ports, orchestrations, maps, pipelines, adapters, schedules, partners. This is the layer people mean when they say documentation, and it is the only one a tool can produce on its own. It is also the least valuable, because it tells you the size of the problem and nothing about the shape.
What it does
For each flow: what triggers it, what it transforms, where it sends the result, what it does on failure. Recoverable by reading the artifacts, slowly, by someone who understands the platform. This is the layer the writer is usually hired for.
Why it does it that way
The map that strips a field because one partner’s parser choked on it in 2014. The retry with an odd interval because a downstream system rate-limits silently. This layer is not in the artifacts at all. It exists in people, tickets and mailing lists, and it is where migrations actually break.
Why this is the expensive layer
Layer 2 tells you how to rebuild the flow. Layer 3 tells you why rebuilding it faithfully from the schema will fail. A rebuild that matches the documented behaviour and not the actual behaviour passes testing and breaks in week one of production, because the tolerance nobody documented is the thing production depended on.
Who notices when it stops
The consequence map. Which flows have a person on the other end who will call within the hour, which have a partner who will notice at month-end, and which nobody would miss. This is the layer that lets you sequence a migration by risk instead of by artifact count — and almost nobody captures it.
A documentation workstream that produces only layers 1 and 2 has produced a very thorough description of a system whose real behaviour is still unknown. That is the common failure, and it is expensive because it looks like success.
02 / Where to start
Start from the traffic, not from the console
The instinct is to open the administration console, list everything, and work down the list alphabetically. Two months later you have documented a great deal of material, much of it describing flows that have not moved a message since 2019.
Invert it. Pull the message log for the last quarter, sort by volume, and let the traffic tell you what matters.
The retirement candidate list is a by-product of this ordering, and it is often worth more than the documentation. Scope you delete costs nothing to migrate.
03 / Where layer three lives
Four sources that are not the documentation
The ticket queue
Every incident on an integration is a recorded instance of the system behaving in a way somebody did not expect. Two years of tickets, grouped by flow, is the closest thing most estates have to a written behavioural spec — and it is already written, by the people who were paged.
The suspended-message queue
What is sitting in it, and what has historically landed there, tells you which inputs the flow cannot handle and how often reality produces them. A flow with a long history of suspensions has a tolerance problem that no schema will disclose.
The partner, directly
For anything with an external counterparty, asking them what they send and what they expect back takes an email and frequently contradicts the internal understanding. Do this before the migration, not during the parallel run, when a contradiction becomes an incident.
The person, structured
The one who knows. Not a workshop — a scheduled hour per flow, with the artifact open, asking one question: what happens if this arrives wrong? An hour per flow with the right person is worth a week of reading, and it is the only way to capture layer three.
Do not interview the expert about the system. Interview them about one flow, with it open in front of you, and ask what breaks it. Generalities produce generalities; a specific artifact produces the story.
The interview technique that actually works
04 / The artifact
One page per flow, always the same shape
The output should not be a wiki. Wikis grow structure that reflects whoever wrote each section, and nobody reads the second page. What survives is a fixed-shape one-pager per flow, in a single folder, with the same eight headings every time.
Eight headings, one page, no exceptions
05 / Staffing
Who should actually do this
A dedicated writer is the right idea with a hard constraint: a writer can capture layers 1, 2 and 4 unaided, but not layer 3. Layer 3 requires someone who knows what to be suspicious of — who reads a retry interval of 47 seconds and asks why it is not 30.
| Layer | Who | Roughly how long |
|---|---|---|
| 1 — What exists | Tooling, plus an afternoon of cleanup | Days |
| 2 — What it does | A technical writer with platform access and patience | The bulk of the contract |
| 3 — Why it does it that way | An integration engineer, interviewing — not a writer working alone | About an hour per live flow |
| 4 — Who notices | A writer, asking business owners rather than engineers | Days, and frequently the biggest surprise |
The common mistake is funding a writer for nine months and no engineer hours, then discovering in month seven that the document describes the artifacts accurately and the system inaccurately.
06 / Scope
What this post does not cover
This is the documentation workstream: how to capture what the estate does before it moves. The related question — why migrations that skipped this step fail, and in which specific ways — is its own piece: five failure modes we see in production, one of which is exactly the undocumented tolerance described in layer three above.
07 / Next
Start with ninety days of traffic
Before funding anybody, pull one report: every flow, with its message count for the last ninety days. It takes an afternoon, it costs nothing, and it tells you how much of the estate is actually in scope. Most teams find that number is a good deal smaller than the artifact count — and every flow it removes is documentation nobody has to write and a migration nobody has to run.
Our assessment produces the inventory, the traffic map and the flow one-pagers as its output — with an integration architect doing the layer-three interviews rather than a writer working alone. Twenty years running BizTalk in enterprise production, Microsoft V-TSP recognized for BizTalk Server.
Frequently asked questions
How do you document an integration estate that nobody documented?
Start from observed traffic rather than the administration console: pull the message counts for the last ninety days and work down by volume, so the flows that matter get documented first and the dead ones collapse into a single retirement list. Then capture four layers per flow — what exists, what it does, why it does it that way, and who notices when it stops — with the third layer coming from interviews, tickets and the suspended-message history rather than from the artifacts.
Should we document the estate before or during a migration?
Before, because the documentation determines the scope and the sequence. An inventory with traffic attached usually removes a meaningful share of the estate from scope entirely, and the consequence mapping is what lets you sequence migration waves by risk rather than by artifact count.
Is it worth hiring a technical writer for integration modernization?
Yes, with one constraint. A writer can capture the inventory, the flow behaviour and the consequence map unaided. What a writer cannot capture alone is why a flow behaves oddly — the tolerances, the workarounds, the retry interval that is a strange number for a reason. That layer needs an integration engineer conducting structured interviews, roughly an hour per live flow. Funding the writer without funding those hours produces a document that describes the artifacts accurately and the system inaccurately.
What should an integration flow one-pager contain?
Eight fixed headings, the same on every page: trigger, path, volume, failure behaviour, known tolerances, consequence, counterparty, and open questions. The open-questions heading is what makes the set honest — those entries become the test cases for the parallel run rather than surprises during it.
How long does it take to document an integration estate?
It scales with live flow count, not artifact count, which is why the traffic report comes first. The inventory takes days, the per-flow behavioural documentation is the bulk of the effort, and the interviews that capture undocumented behaviour run at roughly an hour per live flow. A large estate is a multi-month workstream; the same estate with dead artifacts removed is frequently half of that.
What if the person who understood the estate has already left?
Then the recoverable sources are the ticket queue, the suspended-message history, and the trading partners themselves. Two years of incidents grouped by flow is the closest thing to a written behavioural specification most estates have, and it was written by the people who were paged. External counterparties will usually tell you what they send and expect if you ask, and that answer sometimes contradicts the internal understanding — which is far better discovered by email than during a cutover.
Does documentation actually reduce migration cost?
It reduces scope, which is the same thing. Most estates carry flows that have not moved a message in years, and the traffic-first approach identifies them as a by-product rather than as a separate exercise. Every flow retired is documentation nobody writes, a migration nobody runs and a test nobody executes.
Jorge Pastorini · Cerebrum City
Cerebrum City is a Microsoft V‑TSP–recognized BizTalk specialist in Atlanta, Georgia, with two decades running BizTalk Server in enterprise production for clients including Humana, Deloitte, JetBlue, and U‑Haul.
Want this mapped against your BizTalk estate?
We inventory your ports, orchestrations, maps, and adapters, flag the interfaces most likely to break, and hand back a staged Azure roadmap. No obligation.
