The documentation habit that halves onboarding time

Loca Johnson

·

18 September 2026

·

Most migrations do not fail in the cutover window. They fail six weeks earlier, in the meeting where nobody wanted to say that the dependency map was incomplete.

We have moved somewhere over four hundred workloads in the last five years, and the pattern is remarkably consistent. The technical work is well understood and largely automatable. What sinks a programme is the set of things everybody assumed somebody else had documented: the batch job that writes to a share nobody owns, the licence tied to a MAC address, the reporting process that runs off a spreadsheet on a desktop under someone's desk.

Start with the dependency map, not the target architecture

The temptation is to design the destination first, because that is the interesting part. Resist it for two weeks. Instrument what you have: network flows, authentication logs, scheduled tasks, outbound connections. The map that comes out of that exercise will contradict your architecture diagram, and the contradictions are the actual project plan.

On one recent engagement the client believed they had 62 applications in scope. Flow analysis found 91, eleven of which were usiness-critical and none of which appeared in any inventory. Discovering that in week two costs a fortnight. Discovering it during cutover costs a weekend of downtime and a great deal of credibility.

A migration plan that cannot be reversed on a Sunday afternoon is not a plan. It is a bet.

Move in reversible increments

Every increment should have a documented path back that has been walked at least once. That discipline slows the early phases and then compounds: by the third wave the team is confident, the runbooks are real, and the change board stops asking for extra approvals because the last six changes went exactly as described.

Wave planning session, week four of a 91-application migration.

What we insist on before the first wave

These five items are non-negotiable in our own engagements, and they are the same five we look for when auditing somebody else's programme:

A dependency map produced from observed traffic, not interviews.

A named business owner for every application, reachable on the cutover weekend.

A tested rollback for each wave, with the test signed off in writing.

Baseline performance figures, so "it feels slower" can be answered with data.

A cost model per workload, reviewed monthly for the first two quarters.

None of this is exotic. It is simply the difference between a migration that ends in a quiet Monday morning and one that ends in an incident review. The organisations that get this right are rarely the ones with the largest budgets; they are the ones willing to spend the first month finding out what they actually have.

Loca Johnson

Specializing in crafting clear, engaging content that helps brands grow and connect with their audience. From SEO-driven articles to in-depth case studies.