The wiki is dead: why walkthroughs replace Confluence pages

The most-quoted line about Confluence is “Confluence is where information goes to die.” It's been a meme on Hacker News, a blog title on Dev, and a recurring complaint in Atlassian's own community forums. The pattern is so familiar it's embarrassing: someone documents a procedure, the procedure changes, the doc doesn't, the next reader hits a wall, the doc loses authority, eventually nobody trusts the wiki and everyone Slacks the senior again.

The reflexive answer is “use a different wiki.” Switch to Notion. Switch to Coda. Switch to GitHub Wiki. Switch to Microsoft Loop. Every team that has done that switch has the same Confluence-shaped problem six months later, with the same dead pages and the same Slack pings to the senior.

The wiki isn't broken because Atlassian shipped a bad product. The wiki is broken because the wiki shape — a blank page someone fills with prose, an unstructured tree of those pages, and a search bar people stop using — is the wrong shape for the procedural knowledge teams keep trying to put in it. This post is about why, and what shape works instead.

Disclosure up front: I work on UIHike, and the alternative-shape we're arguing for is the one we build. The first half of this post is the structural case for why wikis fail at procedure docs. The second half is the practical case for what a walkthrough is and what it replaces.

What wikis are good at

Before the criticism: wikis didn't become ubiquitous for no reason. They're good at a real category of work.

Free-form prose pages — the architecture decision record, the team charter, the postmortem write-up, the strategy memo. Anything where the value is in the argument, the audience reads top to bottom, and the doc is meant to be authored once and edited rarely. Wikis are also good at indexed reference data: glossaries, contact lists, policy libraries. Stuff with a stable structure where prose isn't the wrong format.

For these uses, Confluence is fine. Notion is fine. GitHub Wiki is fine. None of them is going to disappear. The trouble starts when teams use the same shape to document procedures — sequences of clicks, decisions, and page transitions that someone will follow step by step months later.

Why wikis fail at procedural docs

Three structural reasons, all independent of which wiki vendor you picked.

1. Wikis hide freshness

The single most-cited problem with Confluence isn't search. It's that a page reviewed last week and a page written three years ago look identical. Same fonts, same headers, same confident formatting. The wiki has metadata about freshness — last edited date, page history, author — but the metadata is tucked behind menus or in small grey text. The default presentation is “trust me.”

That's fine for a strategy memo (which is a snapshot of a moment) and catastrophic for a procedure (which is supposed to mirror the live system). When a procedure's underlying tool changes, the wiki page keeps presenting the procedure with full confidence. The reader has no signal that anything is wrong until they hit a step that doesn't match reality.

Industry write-ups capture the failure mode bluntly: an engineer following an outdated runbook at 11pm during a production issue, losing 40 minutes to references to renamed services and deprecated tools. The runbook didn't lie on purpose. It just had no way to know it had aged out.

2. Wikis decouple writing from working

The wiki is a separate destination. To use it, you stop what you're doing, switch tabs, open the editor, find or create the page, and write. Most engineers experience that as friction: the doc lives outside the normal development workflow, so it gets written after the fact, when the writer's memory of the work has already lost detail.

The well-known argument lands here: Confluence ends up being a graveyard for docs because it sits outside the normal development workflow. Only after the work is done does anyone go to a separate WYSIWYG editor and decide what to write down. The same dynamic applies to ops, support, and customer success. The doc is always written after the fact, by someone whose memory has already compressed the work.

3. Wikis treat sequences as prose

Procedure docs are sequences. Step 1, then step 2, then step 3. The wiki shape — a blank page, a markdown editor, a numbered list — turns the sequence into prose paragraphs that lose the structure of the underlying steps. There's no first-class concept of “a step.” There's just a paragraph that the author decided to start with the number 1.

The consequences ripple. You can't link to a single step. You can't comment on a single step. You can't track which step a reader bounced off. You can't version a single step. You can't reorder steps without a copy-paste session. Every operation that would be cheap on a structured walkthrough becomes expensive on a wiki page, so the operations don't happen, and the doc rots.

The cleanup-sprint anti-pattern

Every team has tried this. Block off a week. Audit the wiki. Archive the dead pages. Update the stale ones. Add owners. Add review dates. Six months later the wiki is right back to where it was.

The reason cleanup sprints don't stick is that they treat a continuous problem like a one-time event. The wiki rots continuously because the work it documents changes continuously. A sprint pays down the debt; it doesn't change the rate of accumulation. As soon as the sprint ends and the team goes back to scheduled-doc writing, the same dynamics produce the same result.

Worse, the cleanup sprint creates a false sense of freshness. The pages that survive the sprint look authoritative, even when their procedural content is already starting to drift. The wiki gets a green checkmark next to it and the rot begins again from a cleaner baseline.

Walkthroughs are a different shape

The shape that fits procedural knowledge isn't a page. It's a sequence of steps, each captured at the moment the work was done, each containing the structured context the work generated.

In UIHike, that's a recorded session. You start a recording, do the work, and stop. Each click, navigation, form input, and hotkey-triggered region grab becomes a step. Each step contains the screenshot, the page URL at capture time, the page title, the CSS selector of the clicked element, the visible text on that element, the associated label if any, and the typed value (passwords masked). The author edits titles where the auto-fill was wrong, adds short descriptions where useful, and publishes.

The differences from a wiki page are not cosmetic. They're structural.

Steps are first-class. A step has an ID, a number, a screenshot, structured fields, and a comment thread. You can link to step 7 of a walkthrough the way you link to a line of code on GitHub. You can comment on step 7 the way you comment on a line of code. You can update step 7 without touching steps 1 through 6.

Capture happens during work, not after. The author is doing the procedure for real. The recording captures what actually happened, including the steps the author would have forgotten to write down. The doc is a side effect of the work, not a separate project.

Updates are re-recordings, not edits. When the underlying tool changes, the author runs the procedure again with the recorder on. The new walkthrough replaces or supersedes the old one. There's no page-by-page screenshot replacement, no prose-by-prose “is this still right?” audit. The recording either matches the live system or it doesn't, and the failure mode is loud.

Freshness is visible by default. Each step has a capture timestamp. The reader can see whether the screenshots are from this quarter or before the last redesign. The wiki's “everything looks equally trustworthy” problem doesn't apply because the structured capture date is part of the step, not a footer metadata field nobody reads.

What you give up by leaving the wiki

Honest gaps. The walkthrough shape isn't free.

Free-form prose lives somewhere else. A walkthrough is a sequence of steps, not an essay. The architecture decision record, the postmortem, the team charter — those still want a wiki page. The replacement isn't “delete Confluence.” It's “put procedures in walkthroughs and keep prose in the wiki.”

Real-time multi-user editing isn't there yet. If two people need to edit the same step of the same walkthrough simultaneously, with cursors and presence, that's Confluence's territory. UIHike's team members can view and comment on shared walkthroughs; live co-editing of the same step isn't implemented.

Wiki ecosystems are deep. Confluence has a decade of plugins, page templates, space-level permissions, and macro integrations. A walkthrough tool replaces the part of Confluence that documents procedures, not the page-template ecosystem your IT team has built around it. For most teams the right move is to keep Confluence for what it's good at and stop forcing procedures through it.

The hybrid that actually ships

A practical decomposition that most teams settle into:

• Procedural docs go in walkthroughs. Onboarding, runbooks, support playbooks, audit walkthroughs, demo scripts. Anything someone follows step by step.
• Free-form prose stays in the wiki. Architecture, strategy, policies, postmortems, team docs. Reference data — glossaries, contact lists, vendor inventories — stays in the wiki.
• The wiki links to the walkthroughs. Each procedure's wiki page (if it exists at all) is a short cover note linking to the walkthrough. The wiki page may answer “why do we do this?” The walkthrough answers “how do we do it?”
• Search covers both. Whatever your wiki search is good at, keep using it for prose. Walkthroughs are full-text indexable on titles, descriptions, and step content; some teams index walkthrough Markdown exports back into the wiki search to keep one search surface.

That hybrid keeps everything Confluence is good at and reroutes the procedural docs through the shape that fits them.

What the migration looks like

You don't need to migrate the whole Confluence space at once. The pattern that holds up:

Pick the procedure that hurts most when it's wrong. The runbook your on-call follows at 2am. The onboarding doc the new hire gets confused on. The audit walkthrough you have to redo every quarter. The biggest pain is the best test of the new shape.

Re-record it once. The senior who owns the procedure runs it for real with the recorder on. Total time: usually one to two hours of editing on top of the time the procedure already took. The output is a walkthrough with all the structured context the wiki page never had.

Compare side by side. Open the old wiki page next to the new walkthrough. Two questions: which one is faster to update next time the procedure changes? Which one will tell a new hire which Approve button on which page six months from now?

Replace the wiki page's body. If the walkthrough wins, replace the body of the Confluence page with a one-line link to the walkthrough. The wiki URL still works. Bookmarks don't break. The actual procedure now lives in a shape that matches the work.

Repeat with the next-most-painful procedure. Within a quarter the highest-leverage docs have moved. Within a year the wiki is back to being the shape it's good at — prose, policy, reference — and the procedures live where they belong.

The principle

The wiki is dead for procedures. It is fine for prose. The mistake is that teams put procedures in the wiki anyway, because the wiki was the tool they had, and then they wonder why the wiki is full of dead pages.

The fix isn't a better wiki. It's a different shape for the procedural part of the knowledge base. A sequence of steps, captured while the work is being done, with the structured context the screenshot alone is missing. The wiki gets to keep what it's actually good at, and the procedures get to live in a shape that resists the rot.

Try UIHike on the wiki page that ages worst on your team. The first walkthrough takes an afternoon. The Slack pings to the senior stop coming the week after.

— The UIHike team