Documentation doesn't scale. Here's what we learned from organizations that made it work.

We've spent years helping organizations fix their documentation infrastructure—universities managing 145k pages, research institutes with 50+ spaces, teams where half the engineering time goes to “Where did we document that?”

The core problem isn't tooling. It's that documentation systems optimize for writing, not for surviving. And everything that doesn't survive eventually fragments.

What breaks at scale:

• Hierarchical navigation fails around 1,000 pages.


• People organize docs the way they think about them today.


• Six months later, new people can't find anything because they think about the problem differently.


• earch becomes the only navigation, but search assumes you know what you're looking for.

“Just write better docs” doesn't work. We analyzed documentation from teams with strong writing cultures. The issue isn't quality, it's just that context decays. A decision doc from 2022 doesn't explain why certain constraints existed, because everyone in the room knew. New people read it and make the same mistakes.

The wiki/Google Docs/Notion fragmentation is inevitable without structure. Teams start in one tool, hit limits, move some content elsewhere, now you have two sources of truth. We've seen orgs with documentation in 6+ different systems, all claiming to be canonical.

Link rot compounds exponentially.

People rename things, delete outdated content, don't update references. After 3-4 years, 20-30% of internal links are broken.

What actually works:

• Structured content, not just markdown. Metadata about “what type of doc is this” lets you build views, enforce review cycles, track ownership. This sounds bureaucratic but it's the difference between searchable and findable.


• Separation of content and presentation. The way you navigate docs should change as the org grows, but the content shouldn't need rewriting. Most tools couple these.


• Explicit ownership and lifecycle. Every doc needs an owner and a review cycle, or it rots. The teams that made this work treated documentation like code—ownership, pull requests, deprecation policies.


• Self-hosting when you care about longevity. SaaS vendors change pricing, deprecate features, get acquired. If your docs matter for 5+ years, hosting them yourself means you control the upgrade cycle.

*We're running a technical webinar on explaining what we've learned through direct experience, if people want the details: *

https://xwiki.com/en/webinars/XWiki-as-a-documentation-tool

But honestly, the interesting question is: has anyone solved this differently? What's worked for keeping documentation usable at scale?