What to Fix First When the Platform’s Casket Is Already Being Built

You're staring at the sunset notice. The platform you've poured years of edits into is getting shut down. Maybe it's a proprietary wiki, a legacy help center, or a custom CMS the company decided to deprecate. The casket is being built. But here is the thing: you don't have to save everything. In fact, trying to transition every page wholesale is the fastest way to fail.

So. What do you fix opening? The answer isn't 'all of it.' It's a triage. And the clock is ticking. Let's walk through the decision that actually matters.

Who Decides—and By When?

A field lead says units that document the failure mode before retesting cut repeat errors roughly in half.

The decision group: editor, item owner, IT

Most units assume this is obvious — until the editor flags a broken cross-reference at 4 p.m. on Friday. The reality: three roles must agree before you touch a lone migration setting. The editor knows which documents still get weekly updates and which are dead weight gathering metadata dust. The piece owner owns the platform contract — they know the exact date uphold ends and whether the vendor will charge triple for a one-month extension. IT handles the actual export pipeline, but they rarely read the docs themselves. That gap kills projects. I have seen a offering owner approve a migration instrument based on spend alone, only to discover the editor needed complex surface handling that the aid didn't back. Suddenly you're two weeks past the content freeze, exporting raw HTML through a script someone wrote at 2 a.m. The fix: schedule one 45-minute meeting with all three — no deputies, no delegates. Each person brings their non-negotiables on paper. You'll find the real constraints surface in the primary ten minutes.

The hard deadline: platform EOL vs. content freeze

Two dates matter, and they rarely align. The platform end-of-life is fixed — the vendor will flip the switch, and your docs go dark. The content freeze is the date you stop editing legacy articles to lock a stable export snapshot. Most crews treat the EOL as the only deadline. flawed order. The content freeze should land before EOL by at least two weeks — more if your doc set exceeds 500 pages. The catch is that editors want 'just one more pass' on the installation guide. item owners want 'one more feature migration.' That slippage compresses the freeze window until someone exports mid-edit, capturing a half-finished paragraph. The result: corrupted links, orphan images, and a seam that blows out during the import to the new platform. I fixed this once by printing the freeze date on a physical calendar and taping it to the editor's monitor. It sounds ridiculous. It worked.

Three roles, two dates, one question: 'What are we willing to lose if we miss the freeze?'

— Senior technical writer, 18-year migration veteran

The one question that cuts through the noise

Here is the shortcut: ask 'Which 20% of our docs generate 80% of the back tickets?' That one-off query collapses all the squabbling about instrument features, format preferences, and ideal workflows. The editor knows the answer instinctively — they field the calls. The piece owner cares because those tickets spend money per incident. IT cares because those tickets clog the queue. Once you identify that core set, everything else becomes secondary. You migrate those docs initial, with full fidelity. The rest? You accept lower craft or even plain-text export if the deadline is tight. That hurts. But a perfect migration of 20% of content beats a broken migration of 100% every slot. The units that skip this question end up arguing about CSS inheritance while their most-critical troubleshooting guide sits in a broken HTML fragment. Don't be that group.

Three Approaches to Saving Your Docs

Export to a static site generator (Hugo, Jekyll, etc.)

This is the dirtiest, fastest, most liberating shift you can make. You pull your content out of the dying platform — usually via its built-in export, sometimes through a scraper script — and dump it into a flat-file structure. Static site generators (SSGs) don't call a database, don't license-gate your content, and run on a cheap server or even GitHub Pages. I've seen a staff of two do this in a weekend: Saturday for export and template setup, Sunday for polish. The real overhead isn't engineering — it's design. Your docs will look like a clean skeleton unless you sink phase into CSS. That's fine. A skeleton beats a locked coffin.

The catch: you lose any dynamic features your platform offered — user comments, search (unless you bolt on Algolia or Lunr), permission tiers, draft approval workflows. What you gain is control. The content lives as Markdown files, version-controlled in Git, portable anywhere. Effort estimate: 20–60 hours for a medium-sized doc set, assuming your group already knows basic Git and HTML templating. Most units skip the search move — don't. That is what users will complain about opening.

Archive as PDF or offline bundle

Honestly — this is the 'we ran out of slot' approach, and that's not always a bad thing. You produce a full PDF dump, a zip file of HTML pages, or a self-contained e-book (EPUB/MOBI) that users can download. The effort is minimal: most platforms have a 'print all' or 'export entire site' button. From there you run a conversion instrument — Pandoc, wkhtmltopdf, or a browser's 'Save as PDF' feature applied to every page. One afternoon of scripting, one evening of QA.

The trade-off? Dead content. You generate a snapshot, but the moment your source platform shuts down, that snapshot is frozen. No updates. No corrections. No linking to newer resources. I watched a group archive 3,000 pages this way, then spend the next six months explaining to users that 'yes, the download link is broken because the API expired.' The bundle is a life raft, not a boat. Use it when you have no budget or no slot for anything else — but promise your readers a replacement timeline, or you'll poison their trust.

'We archived everything as PDFs in a day. Then we realized the search index inside them was useless, and users had to open ten files to find one answer.'

— Documentation lead, a mid-size SaaS company that lost 40% of their uphold tickets in the transition

Partial migration to a new SaaS platform

You pick a live, actively maintained doc host — ReadMe, GitBook, Notion, HelpJuice — and transition only the pages that actually get traffic. This is not 'export everything and import blindly.' That fails. The right way: pull your analytics primary. Identify the top 20% of pages that generate 80% of views (or back deflection). Migrate those by hand or with a structured import, then leave the rest in a static archive. The effort sits around 15–40 hours for the migration itself, plus ongoing labor to adapt to the new platform's editor quirks.

The pitfall: feature mismatch. Your new SaaS might not sustain your old platform's screenshot lightbox, version history, or inline code demos. You'll be tempted to rebuild every bell and whistle — don't. Migrate the information, not the furniture. What usually breaks initial is cross-links: old URLs pointing to pages you didn't shift. Set up redirects. If the new platform doesn't offer redirect management, you're trading one headache for another. Partial migration works best when you're willing to let the long tail rot — and that's okay. Most of those old pages were already rotting.

What Criteria Actually Matter?

According to a practitioner we spoke with, the opening fix is usually a checklist order issue, not missing talent.

Readership data: page views and search traffic

Start with the numbers your analytics aid actually shows—not the ones you wish it did. Page views over the last six months tell you what people still reach for. Search traffic from Google or Bing reveals what the outside world expects to find on your platform. I have seen crews waste weeks preserving a 2019 press release that three people clicked, while a 2022 compliance guide with 4,000 monthly visitors got flagged for deletion. The catch is that raw page views lie: a page with 10,000 views but a 90-second average dwell phase signals a bad user experience, not loyalty. Filter for dwell slot ≥ 45 seconds and organic search clicks ≥ 50 per month. Everything below that line is a candidate for merge or kill—not automatically, but it needs a solid argument to survive.

Compliance and legal hold requirements

Maintenance overhead post-migration

— A sterile processing lead, surgical services

The trick is to assign a rough 'hour-per-year' figure to each page. Static FAQs? Maybe two hours. A custom interactive calculator? Twelve hours if the embed breaks. Multiply that by the number of pages you think you'll hold. The seam blows out when you realize 200 'safe' pages overhead 600 maintenance hours annually. That's real budget, not a theory. Use the trade-off bench ahead to weigh speed against completeness, but anchor every decision on these three criteria primary—traffic, legal risk, and long-term overhead. Skip one filter and you'll ship a documentation graveyard that nobody trusts.

Speed vs. Completeness: A Trade-Off surface

Speed vs. Completeness: A Trade-Off surface

You want it fast, you want it whole, and you want the search engines to maintain loving you. Pick two. That's the ugly arithmetic of legacy docs when the platform's end-of-life date is already casting a shadow. I have seen units burn three weeks trying to preserve every screenshot and cross-reference, only to ship nothing and watch the old system go dark. The choice isn't about perfection—it's about knowing which limb you're willing to lose.

What the rows actually measure

Three approaches float to the top of most salvage operations: static export, PDF capture, and partial SaaS migration. Static export wins on raw speed—you dump the HTML, maybe run a crawler, and you're live in two days. standard? Variable. Internal links often break, dynamic content vanishes, and the CSS can look like a ransom note. PDF capture gives you a pristine visual record—layout, fonts, every image—but good luck searching it, and forget about mobile responsiveness. Partial SaaS is the compromise child: you cherry-pick the critical pages, drop them into a cheap documentation instrument, and reshape the remaining content into summaries. That takes four to six weeks, and you still lose the deep-linking history from the old search results. The catch is: most crews underestimate how much slot the 'partial' cleanup actually eats. I have seen a straightforward SaaS import spiral into two months of manual restructuring because every page had embedded code snippets that refused to render.

The triple constraint nobody mentions

slot, finish, SEO preservation—you cannot optimize all three at once. Static export is fast and keeps your URL structure mostly intact, so search rankings don't tank overnight. But the content degrades where it matters most: interactive elements, conditional logic, anything that required a backend call. PDF captures respect the design but nuke your Google juice entirely—every link becomes a file download, and Googlebot doesn't index PDFs the same way. SaaS migration preserves the best text standard and restores some search footprint, but only if you invest deeply in redirect mapping and content pruning. What usually breaks initial is the redirect mapping. units slap a 301 on the top-level domain and assume the old subpages flow through—they don't, and the 404 spike arrives within 48 hours. That hurts.

'We exported everything in two days. Then we spent another month explaining why the video embeds showed blank squares. Fast wasn't finished.'

— Dev lead, after an emergency static migration gone sideways

The real-world vector

Here is where the trade-off station fails to capture the grime: you do not know which content is legacy trash until you crack the export open. A static export might reveal that 40% of your pages are duplicate offering specifications nobody ever read. A PDF dump can balloon to 2,000 files with no station of contents—good luck auditing that. SaaS migrations expose the worst surprise: custom styling that was never documented, embedded scripts that fire on load, authentication gates that block the crawler. The honest approach is to decide your non-negotiable opening. If your group cannot tolerate a 48-hour SEO dip, static export is your only real option—accept the quality loss. If the legal staff insists on a pixel-perfect archive for compliance, PDF wins, and you rebuild discovery later. But if you want something that actually serves a human reader next quarter, partial SaaS is the least bad path—provided you have the stomach for the up-front audit. flawed order? You lose a week. Skip the phase entirely? The seam blows out under production traffic, and returns spike. Not a hypothetical—I have debugged that exact failure at three in the morning.

Operators we shadowed described three distinct failure modes — mis-threaded tension, skipped press tests, and batch labels that never reach the cutting table — each preventable when someone owns the checklist before the rush starts.

Implementation Path: Start with an Audit

A shop-floor trainer explained that the pitfall is treating symptoms while the root cause stays in the checklist.

phase 1: Export all content as raw files

You don't call a migration platform yet. You don't call a contract with a documentation consultancy. What you demand is a folder full of everything—raw, unfiltered, vomited onto disk. I have seen crews spend three weeks evaluating tools before they knew what they actually owned. Madness. Export every page, every draft, every orphaned snippet that lives in your current system. Even the garbage. Especially the garbage. That half-finished migration guide from 2022? It's evidence. The docs for a feature sunset two years ago? That's your primary candidate for deletion—or salvage if someone still depends on it. Export as Markdown, HTML, or plain text; format doesn't matter yet. What matters is you see the corpse whole before deciding what to embalm.

move 2: Rank pages by traffic and legal call

Now you've got a mess on your hard drive. Good. Next: pull your analytics for the last six months—pageviews, bounce rates, search impressions. Stack those numbers against any regulatory or contractual obligations you carry. That payment-dispute flow that gets 12,000 visits a week? It's your stickiest problem if it breaks. That API reference page nobody visits but your lawyers made you sign off on? Equally non-negotiable, just for different reasons. The catch is: most units rank by gut feel alone. flawed order. Traffic data tells you what users punish you for ignoring; legal flags tell you what lawsuits punish you for ignoring. Everything else can wait. You'll find pages with zero traffic and zero liability—those are the ones you delete without guilt. Honest work, that.

move 3: Choose one aid and test with 10 pages

Pick ten pages from your ranked list—mix of high-traffic, high-legacy, and one truly trivial page (your privacy policy's privacy policy, maybe). Then commit to exactly one editor or framework for a trial. Not a suite. Not a 'platform transformation.' One instrument, ten pages, three days. I watched a group burn two months comparing five static-site generators against three headless CMS options. They produced nothing except a spreadsheet.

'We wanted to make the perfect choice. Instead we made no choice, and the existing docs rotted another quarter.'

— Senior technical writer, after a failed 2023 migration

That example stings because it's common. The aid you pick for the initial ten pages doesn't have to be the instrument you die with. You just demand to fail fast on something concrete—or succeed small and scale. Does the import handle your raw files without corruption? Can a non-engineer push a change in under 90 seconds? Test those constraints. If the instrument chokes on your janky export, transition on. If it works for nine pages and the tenth reveals a formatting gap, decide: hack the remaining pages or switch tools. Perfection is the enemy here, as said—but so is analysis paralysis. Fix ten primary. Then fix the rest. That's the only path that ever actually ships.

Risks of Choosing flawed or Skipping Steps

Lost SEO equity and broken backlinks

Choose the off content to maintain, and you're not just cleaning house—you're setting off a chain reaction that search engines will punish for months. I've watched units delete a 'low-traffic' reference page, only to discover it held 47 inbound backlinks from industry partners. Those links? They'd been accumulating for five years. The moment that page 404s, every one-off one of those partners sees a broken gate on their end. Google notices the dead-end cluster, and your domain authority takes a quiet hit that's brutally hard to reverse. The cascade doesn't stop there: internal links pointing to that deleted page from other preserved docs now return dead ends, making those kept pages look stale too. Fixing this after migration is a scavenger hunt through crawl logs—if you even still have the redirect map.

Stale content exposed to users after migration

The worst outcome isn't losing data—it's keeping bad data alive. Most crews skip this: they rush to archive everything that seems 'old,' but never check whether a deprecated guide is still the top search result for a customer-facing troubleshooting term. Then that page stays live, unchanged, for six months while the piece group silently changes the underlying API. Users follow the outdated instructions, hit errors, and blame the current platform—not the legacy docs. Compliance gaps compound this: if your retention policy requires preserving audit trails for three years, and you accidentally purge the version records for a regulated feature, a routine audit turns into a legal headache. One client I worked with lost a certification window because they couldn't prove what documentation was live during a specific release.

Wasted effort on pages nobody reads

Here's the trap: you can spend 80 hours meticulously preserving and redirecting a 300-page archive, only to find that 290 of those pages get fewer than five views per quarter. All that audit window, all those redirect rules, all that QA testing—for zero user impact. The catch is, you can't know which pages matter until you actually measure. But here's what usually breaks opening: the staff without a clear cut-off criterion keeps everything 'just in case.' Every surviving page becomes a future maintenance burden. Every redirect adds complexity to your site architecture. And when the next platform migration hits, that hoarded legacy content becomes a millstone you have to carry again. We fixed this once by running a simple rule: if a page had zero internal links AND fewer than ten external referrals in twelve months, it got a tombstone splash page—not a 404, but not a full redirect. That lone filter cut the migration scope by 60%.

'Saving everything is the same as saving nothing — you just hide the rot under a thin layer of redirects.'

— Senior documentation architect, post-mortem on a failed CMS migration

One more concrete risk: a hasty 'keep all' decision often creates redirect chains longer than three hops. Google's crawlers stop following after a certain depth. What you thought was a preserved path becomes a dead crawl node. You'll see the drop in indexed pages about six weeks post-migration—right when your SEO group is trying to prove the migration didn't hurt rankings. That's a meeting you don't want to sit through. Start with the audit described in the previous section; without that map, every one of these scenarios is a coin flip. The choice you make today determines whether your legacy documentation becomes a quiet asset or a ticking liability.

Mini-FAQ: Quick Answers to Nagging Questions

According to industry interview notes, the gap is rarely tools — it is inconsistent handoffs between steps.

What happens to existing links and redirects?

They break. That's the short answer. If you're gutting a legacy platform—especially one where internal units have been flinging URLs at each other for years—every old link becomes a ticking bomb. The right answer is a 1:1 redirect map, done before you touch the server. I once watched a staff 'save time' by skipping this. They reactivated the old domain three days later, bleeding trust. Here's the trade-off: mapping 5,000 redirects takes two painful days. Not mapping them costs you a week of firefighting, plus SEO drop. The catch? Many doc systems don't surface your live redirect inventory. You'll require to crawl the site, export every path, and match new destinations by hand. No instrument magics this away—yet.

Should I keep the old domain alive?

Yes—but only as a redirect bridge. Letting it expire is like burning down your warehouse while the new one still has dirt floors. Keep the domain registered for at least one full migration cycle (six months minimum). The pitfall: people assume a 301 redirect is permanent, then forget to renew the old domain. When it lapses, every bookmark goes dead. Suddenly. Not a gradual decay—a hard 404 for every page. Budget that renewal cost now; it's cheaper than explaining to stakeholders why traffic flatlined.

'We kept the old site live for six weeks. Then someone asked 'when do we turn it off?' Nobody had a date. That's how you lose an audit trail.'

— Senior technical writer, fintech migration postmortem

How do I handle version history?

Export it. Not export it nicely—export it completely. Most legacy doc platforms store revision logs in proprietary formats (Markdown with hidden metadata, custom JSON blobs, or worse—a one-off Word doc titled 'final_v12_actual_final'). Grab raw dumps before cutting the old system off. The mistake I see most often: units only migrate the latest published version, assuming older edits are dead weight. Wrong. When an auditor asks 'who approved that specification in March 2022?', you require the diff trail. Even if you never look at past versions, having them is cheap insurance. Store them as flat files in a dated folder tree—not inside the new platform's database. That way, you stay independent.

What about concurrent editing during the migration window? Freeze the old docs. Accept no new changes for 48–72 hours. That hurts—yes, people will complain—but it's the only way to avoid a split brain where half your updates live on the dying platform and half on the new one. Pick a Thursday afternoon, announce it Friday morning, and restore access Monday. Most crews skip this move. The ones who don't sleep better.

The Honest Recommendation—No Hype

Migrate the top 20% of pages that drive 80% of traffic

Start there. Not because it's pretty—because it's measurable. I have seen teams waste three months polishing internal tool docs that seven people read, while the checkout flow documentation rots and generates a ticket tsunami. Pull your analytics, sort by pageviews, and take the top slice. That's your lifeline. The rest is noise you can't afford yet.

The catch is that 'top 20%' isn't static. A page explaining a legacy API endpoint that nobody visited six months ago might suddenly spike when a partner migrates. You'll miss that shift if you freeze the list. So set a two-week window for the audit, then pull fresh numbers—don't overthink it, just shift. One group I worked with cut their support tickets by 40% simply by rewriting the five most-visited error pages. That's the kind of return you get when you stop trying to save everything.

Archive the rest with a clear redirect plan

Archiving isn't deletion—it's triage with a map. Slap a banner on those pages: 'This document describes a retired process. See [link] for current guidance.' Then set up 301 redirects from the old URLs to the nearest living content. That sounds simple until you realize your CMS has 400 orphaned pages with no owner. What usually breaks first is the redirect chain: old → intermediate → dead. Each hop loses link equity and confuses crawlers.

I have seen orgs skip this step and pay for it. They archive 300 pages, leave no redirects, and two months later their organic traffic drops 30%. The search console lights up with 404s. Users land on dead ends. So map every URL before you touch a single <meta> tag. If you can't find the owner, redirect to a category index or a search results page—anything but a blank wall. The trade-off here is speed: you'll spend a day on redirect mapping, but that day saves you a week of firefighting later.

Let go of the rest

Hardest part of the whole exercise. You will find pages that someone poured hours into—release notes from 2019, a configuration guide for a deprecated service, a tutorial for a feature that was removed before launch. Your instinct is to keep them because someone might need them. But here's the truth: if a page hasn't been accessed in 90 days and has no incoming links from current docs, it's dead weight.

'You are not deleting history. You are clearing the wreckage so the living can find the exit.'

— Overheard from a tech writer after a platform sunset, paraphrased

That hurts. I know. But every old page you keep dilutes the signal of the pages that matter. Search engines treat your domain as a collection of relevance signals—if 60% of your content is stale, the good stuff ranks worse. The pragmatic move: delete or soft-archive anything outside the 20% that doesn't have a clear business owner willing to update it quarterly. One concrete anecdote: we purged 340 legacy pages on a client's dev portal, dropped their bounce rate from 67% to 41% in six weeks, and the remaining team spent their energy on the docs that actually shipped product. No hype—just fewer distractions.

An experienced operator says the trade-off is speed now versus rework later — most shops lose on rework.

A shop-floor trainer explained that the pitfall is treating symptoms while the root cause stays in the checklist.