Four incompatible content management systems, eight years of accumulated technical debt, twenty-three undocumented integrations, and two previous failed migrations. After a dependency-first migration architecture — not a big-bang cutover — the four systems were consolidated into one, the twenty-three integrations were mapped and preserved, and the cutover completed with zero data loss. The two previous attempts had failed for the same structural reason, and that reason had nothing to do with the technology being migrated.
The starting state: a large enterprise technology company whose internal documentation platform served thousands of users across multiple business units. The platform had started as one system. Over eight years of acquisitions, reorganizations, and pragmatic local decisions, it had become four. The challenge: consolidate the four systems into one without breaking the workflows, integrations, and human habits that had calcified around the fragmented state.
Starting Conditions
The content platform was the backbone of internal knowledge management for thousands of users. Engineering documentation, product specifications, process runbooks, compliance artifacts, and operational knowledge all lived inside some combination of the four systems. For most users, "the docs" was an abstraction that hid which of the four systems they were actually touching. For the operations team, "the docs" was a constant source of friction — the same document could exist in two systems with different version histories, searches could return stale results from one system while fresh content lived in another, and there was no authoritative answer to the question of which version was current.
Scale of the debt. The four systems had accumulated eight years of content. Nobody on the current team had been present for the original architectural decisions. The systems had been inherited through reorganizations, the institutional knowledge about why they were separate had dissipated, and the documentation describing the systems was itself stored across the four systems in inconsistent forms.
Two previous failed migrations. The organization had attempted consolidation twice. Both attempts had treated the migration as a content problem — identify the authoritative content, move it into a new system, decommission the old ones. Both had run into the same failure pattern: the cutover would start, downstream integrations and user workflows that depended on the old systems would begin to break in ways that had not been anticipated, the operations team would have to freeze the migration to investigate, and the frozen state would become the new permanent state. The second failed migration had left the organization with a fifth partially populated system alongside the original four, which made the technical debt problem worse, not better.
Political constraint. A third failed migration was not an option. The credibility cost of the first two failures meant that any new attempt had to have a defensible plan for avoiding the specific failure mode that had killed the previous two. "Do it more carefully" was not a plan. A plan required naming the structural reason the previous attempts had failed, and then designing against that reason specifically.
Operational constraint. The content platform could not be taken offline. Thousands of users depended on it for daily work. Any migration architecture had to assume that the old systems remained live and serving traffic throughout the cutover. This ruled out the big-bang migration pattern that had been attempted both previous times.
Search and version-control state. Search functionality was returning stale results because each of the four systems maintained its own index, and the indexes had drifted out of sync with the actual content. Document versioning had no single source of truth — a document could have one version history in System A and a parallel version history in System C, and reconciling which was authoritative required a human to read both and decide. Users had responded to this uncertainty by hoarding local copies, which created a sixth tier of content that lived on individual laptops and was invisible to governance entirely.
Structural Diagnosis
Three architectural problems explained why the previous migrations had failed and why the next attempt would need to be structured differently.
The previous migrations had mistaken content migration for a data migration problem. Data migration is the tractable subset of the work — moving bytes from one system into another, preserving encoding, preserving metadata, handling format conversions. The previous attempts had invested heavily in the data migration machinery and had assumed that once the content was in the new system, the old systems could be decommissioned. What this framing missed was that the content was the easy part. The integrations, the workflows, and the human habits that had built up around the old systems were the hard part — and they were effectively invisible to anyone looking at the problem as a data migration. The structural fix was not to build better data-migration tooling. It was to change what was being migrated first, and the content was not the right thing to migrate first.
The dependency graph between content systems, consumers, and integrations did not exist anywhere in documented form. This was the concrete manifestation of the first problem. When a consumer system depended on a specific URL pattern, a specific API contract, or a specific document format from one of the four content systems, that dependency was usually not written down. It had been set up years ago by an engineer who had since left, it had worked continuously ever since, and nobody currently in the organization knew it was there. The previous migrations had discovered these dependencies the same way both times: by breaking them during the cutover and triaging the incident reports. Any migration architecture that assumed the dependencies were knowable in advance was going to encounter the same failure mode. Any migration architecture that assumed they were not knowable in advance had to include a dedicated discovery phase whose only job was to surface them before the cutover touched anything.
The missing architectural question was not "what should we migrate?" but "in what order do the pieces of the current system depend on each other?" The previous migrations had started from a content-first ordering — migrate the biggest, most important, most visited content first, on the theory that it delivered the most value fastest. This is the classic migration mistake. Core content has the most integrations pointing at it, which means it has the most ways to break during cutover. Starting with core content is starting with maximum blast radius. The structural insight that the previous attempts had missed was that dependency order is the inverse of value order: the right thing to migrate first is the least-integrated leaf content that nothing else depends on, and the core systems that everything else points at should be migrated last, when the dependencies pointing at them have already been remapped.
The Intervention
The migration was designed in three phases with dependency order as the controlling principle, not content importance or migration convenience.
Phase 1: Dependency Mapping
What was built: A complete dependency graph of the content systems, their consumers, their integration points, and the user workflows that depended on each. The graph was constructed bottom-up, starting from the four content systems themselves and tracing outward to every system that called into them, every user workflow that referenced them, and every downstream report or dashboard that consumed their data. The phase took three weeks. It did not touch any content. It did not change any configuration. Its only output was the graph.
Why this phase came first: The previous migrations had failed because they did not know where the dependencies were until the cutover broke them. The only way to not fail for the same reason was to build the dependency graph before touching anything, accept that the graph-building would be expensive and would produce no user-visible progress, and treat the graph itself as the most important deliverable of the engagement. Every dollar spent on discovery in this phase would avoid a much larger cost of failed cutover, triage, and organizational credibility loss later.
The mechanism: The mapping process was deliberately inclusive. When in doubt about whether a dependency was load-bearing, it was added to the graph. A dependency that was recorded and turned out to be trivial cost a few minutes of verification. A dependency that was missed and turned out to be load-bearing would cost a production incident. The asymmetry justified over-inclusion. The phase surfaced twenty-three undocumented integrations — systems that depended on the content platform in ways that nobody currently in the organization knew about. Every one of those twenty-three was a failure mode the previous migrations had either tripped on or would have tripped on.
First-phase outcome: A complete dependency graph that described, for every content artifact and every integration, what pointed at it and what it pointed at. This was the input to the rest of the migration. Without it, the rest of the migration would have been blind.
Phase 2: Strangler-Pattern Cutover
What was built: A strangler-fig migration architecture in which new content flowed exclusively through the new system from day one, while existing content remained live in the old systems and was migrated in dependency order — leaf nodes first, core systems last. The new system intercepted writes immediately. Reads continued to resolve against whichever system currently held the authoritative copy of a given document, with the resolution logic informed by the dependency graph from Phase 1.
Why this phase depended on Phase 1: The strangler pattern only works when you know which nodes are leaves and which are core. Without the dependency graph, the strangler reverts to a big-bang migration disguised as incrementalism — content gets moved in whatever order seems convenient, the moves break dependencies randomly, and the operations team is back in triage mode. With the dependency graph, the strangler produces its intended benefit: each migration step is scoped to content whose dependents have already been remapped or whose dependencies are known and intentionally left intact for later phases.
The mechanism: Dependency order meant that the first content migrated was the content with the fewest external pointers into it — old archives, deprecated documentation, content that users rarely touched and no automated system referenced. When that content moved, nothing else broke, because nothing else was depending on it. The second wave was content with a small number of well-understood dependencies, each of which was remapped to the new system before the content moved. The core systems — the content that every other system depended on, the content that the previous migrations had tried to move first — were migrated last, after the population of dependents pointing at them had already been drained.
Tradeoff introduced: The dependency-order sequencing is slower than a big-bang cutover on the timeline the executive team expects. Leaves-first is counterintuitive to anyone thinking about user value, because the leaf content is definitionally the content users care about least. The phase had to be defended on the grounds that slow and correct was the only way to beat the two previous failures, and that the previous failures had been faster on paper and had ended in rollback. Slower is not free. Users continued to experience the fragmented state for longer than they would have with a big-bang cutover. The tradeoff was justified by the outcome of the two previous attempts.
Phase 3: Verification Gates
What was built: A three-step verification routine applied to every batch of migrated content: a data integrity check against the source system, an integration smoke test that exercised every dependent system identified in the Phase 1 graph, and a user acceptance sample that confirmed the migrated content was reaching real users correctly. No batch was declared complete until all three verifications passed. A batch that failed any verification was rolled back to the source system and re-scoped.
Why this phase was continuous, not final: The verification gates did not exist as a distinct step at the end of the migration. They were part of every batch throughout Phase 2. This was a deliberate inversion of the "validate after migration" pattern that had let the previous migrations accumulate undetected problems until the end. The gate ran on every batch, not at the end, because a problem that was caught after ten batches was much easier to diagnose than a problem that was caught after a hundred.
The mechanism: The integration smoke test was the most important of the three verifications because it was the one the previous migrations had skipped implicitly. The data integrity check verified that the bytes had moved. The user acceptance sample verified that humans could find the content. The integration smoke test verified that the twenty-three undocumented integrations were still functioning — it was the check that most directly exercised the failure mode that had killed the previous attempts. Without Phase 1's graph, the smoke test would have had no idea which integrations to exercise.
Constraint and tradeoff: The verification gates added batch-level overhead that the big-bang cutovers would not have incurred. Every batch had to wait for verification before the next batch could start, which slowed the overall cutover. This was accepted as the explicit cost of not repeating the previous failures. The organization had learned the hard way that fast and broken was more expensive than slow and correct.
Results
Four content systems consolidated to one. The final state of the migration delivered the outcome that the two previous attempts had failed to deliver. The four systems were reduced to a single consolidated platform, the fragmented version histories were reconciled, and the search index finally had a single authoritative corpus to build against.
Twenty-three undocumented integrations mapped and preserved. Every integration identified in Phase 1 survived the cutover. The mechanism was Phase 2's dependency-order sequencing and Phase 3's batch-level smoke testing — neither of which was possible without the Phase 1 graph. The previous migrations had not survived because they had not known about the integrations until they broke them.
Zero data loss during migration. The combination of strangler-pattern writes, leaves-first migration order, and three-step batch verification meant that no content was lost in transit and no integration was silently broken. The result is stated in the negative because the measurable outcome is the absence of incidents, which is always harder to see than the presence of them.
Counterfactual. Without the dependency-first architecture, the most likely outcome was a third failed migration on the same pattern as the first two — initial enthusiasm, content-first cutover, cascading integration failures, triage mode, frozen state. Based on the precedent of the previous two attempts, a third failure would have been terminal for the consolidation effort. The content platform would have continued to exist as four systems for the indefinite future, with the sixth tier of user-hoarded local copies continuing to grow. The dependency-first approach did not just produce a better migration. It was the only path that survived.
Framework longevity. The dependency-first migration pattern — exhaustive graph discovery first, strangler cutover in leaves-first order, batch-level verification gates including explicit integration smoke tests — has since been applied to other consolidation engagements in the portfolio. The structural principle holds across content systems, data platforms, and legacy application replacements because the underlying failure mode it addresses is universal.
The Diagnostic Pattern
The organization did not have a content migration problem. It had a dependency mapping problem disguised as a content migration problem. The previous two attempts had failed not because the content was hard to move, but because the operations team had been asked to move content whose downstream dependencies were invisible to them.
Every migration is really a governance transition disguised as a technology project. The technology — which system is the source, which system is the destination, how bytes move between them — is the tractable subset of the work. The governance — which workflows depend on what, whose approval is required to change a dependency, how the organization rolls back when something breaks — is the hard part, and it is the part that determines whether the migration succeeds or joins the list of failed attempts.
The diagnostic pattern transfers to any consolidation where the current fragmented state has been in place long enough for institutional memory of the original reasons to dissipate. The question to ask is not "which system should we migrate to?" That question is the easy one, and it is usually answered before the real work begins. The question that determines success is: which dependencies on the current fragmented state do we not yet know about, and what is the cost of discovering them during the cutover versus discovering them before? Once that question is taken seriously, the rest of the migration architecture — dependency-first discovery, leaves-first sequencing, batch-level verification — follows from the answer.
Related Service
This engagement falls under my PMO & Governance practice.
View advisory engagement models