Every few years a team moves its documentation. A new wiki, a new tool, a merger that brings two systems together. The migration itself is a technical problem, and a solvable one. What I think is actually hard, and what most teams avoid by moving everything, is deciding what deserves to move.
Everything is not an answer
Moving everything feels safe. Nothing is lost, nobody has to decide, and the new system starts with the same contents as the old. I think it is the worst option, for a reason that only shows up later: the new system inherits the old system's problem, which was that nobody could find anything because most of it was no longer true.
Documentation decays. A page written three years ago about how a service works describes a service that has since changed, and a reader who finds it has to work out whether to trust it. Enough of those pages and readers stop trusting any of them. Moving the decay to a new address does not fix it.
The question that decides
The question I use is simple to ask and uncomfortable to answer: who will read this next year?
Not who might. Who will. If a page has a reader in the next year, a specific kind of person with a specific reason, it moves. If the honest answer is nobody, it does not, however much work went into it.
What I keep
Decisions and the reasons for them. These are the most valuable pages a team has and the least likely to be re-created, because the people who knew the reason move on. A decision record from five years ago is still useful five years later if it says why.
Runbooks that are opened. The ones that get used during incidents, that a new on-call engineer follows. You can usually tell which ones those are by asking the people on call.
The onboarding path. Whatever a new engineer reads in their first weeks, in the order they read it. This is the documentation with the most reliable reader.
Anything that describes a boundary or a contract between teams. Those are read every time someone has to work across the boundary, which is often.
What I let go
Status reports and project updates. They were written for a moment and the moment passed.
Meeting notes older than a quarter or so. If a decision came out of the meeting, it belongs in a decision record. The notes themselves are not read.
Pages about systems that no longer exist. This sounds obvious and is the largest category in most old wikis.
Drafts, duplicates, and the three slightly different versions of the same guide. Pick one, or write a new one, and let the rest go.
Migrate by asking, not by copying
The practical way to do this, I think, is to ask rather than to audit. Ask each team which pages they opened in the last six months. Ask the people on call which runbooks they used. Move those, and the decision records, and leave the rest in the old system in read-only form for a year in case someone comes looking. In my experience almost nobody does, and the few who do find what they need.
Where this stops being true
Some records have to be kept whether anyone reads them or not: anything with a legal, contractual, or compliance reason to exist. Those are not documentation in the sense I mean, and the question of who will read them is not the right question. Keep them, label them as what they are, and keep them separate from the pages people actually use.
Photo source: https://photos.robertstowe.com/coronado-national-memorial