The Forgotten Layer
Every infrastructure has a critical layer that doesn't show up on dashboards, but without it, everything slows down: documentation.
We learned this the hard way.
A little background for you. My team and I provide cloud services on a private cloud. This means that our customers are developers. We deliver platform features, portal functionality, maintenance, and infrastructure services. Over the last years, we invested heavily in automation and feature delivery — the things every PO dreams of. That focus allowed us to onboard more and more platforms onto our cloud service offering.
But there was one thing we consistently deprioritized: documentation.
And our customer-facing service docs paid the price.
For years, it lived in Confluence spaces — large, tangled forests of pages where knowledge went to die. And of course, search functionality is also particularly bad using Confluence. So whenever a client reached out and asked if this part of the service information was still valid, the advice was always the same:
"I am not sure, let me double check."
And that worked — until it didn't.
This post is not just a reflection. At the end, I will also share a Docusaurus scaffold we built internally — including linting, theming, and contribution workflows — so you can replicate this approach without reinventing it.
2. The Slow Decay
Documentation debt doesn't scream. It whispers.
At first, it was a broken link here, an outdated diagram there. Nothing dramatic. But as our platform grew, the gap between what we shipped and what we documented widened.
Onboarding stretched from a week to months.
Customers filed support tickets for information that should have been one search away.
When we looked closer, the symptoms all pointed to the same root cause:
- Docs lived outside the development flow
- Ownership was unclear
- Updating them felt like overhead
- And sorry for the dinosaurs out there: Confluence!
3. The Moment Everything Snapped
The real tipping point came in the form of a short email from a customer.
“This page hasn't been updated since 2022.”
We checked. They were right.
Behind that single outdated page lay dozens more in similar shape. We could have patched the page and moved on. But deep down, we knew:
this wasn't a page problem — it was a structural problem.
That was the day we stopped treating documentation as a side activity. We started treating it as part of the product.
4. Why Confluence Couldn't Keep Up
Confluence had served us well in the early years. But we had outgrown it.
Here's why it broke down at scale:
- Disconnected from development: Docs lived in a separate place, updated weeks after features shipped (if at all).
- DevEx: Adding interactive code snippets, or embedding multi-media content is all possible in Confluence, but the writing is cumbersome. Markdown or AsciDocs for the win.
- No versioning: We couldn't align docs with specific releases.
- Search pain: Finding anything meant traversing endless page trees.
- No customer contribution: Feedback loops were slow, often going nowhere.
- No guardrails: No linting, no validation, no CI — which meant quality drift.
And perhaps most importantly:
Confluence didn't create shared ownership.
It was "someone else's job."
5. Before the Tool Came the Story
This might sound counterintuitive for an engineering team, but we didn't start with a tool.
We started with a story.
"If documentation isn't close to the code, it will always be outdated."
This became our North Star. We repeated it in every retro, every cross-team architecture session, and every leadership conversation.
We didn't want just better docs. We wanted documentation to become part of the way we build — fast, iterative, owned by everyone, and open to customers.
Once that vision was clear, the tooling decision became much easier.
6. Choosing the Right Documentation Platform
We ran a structured evaluation of several tools. We needed something that could:
- Git-native workflows
- Versioning
- Fast performance for customers
- Low barrier to contribution
- Enough flexibility without becoming a framework project
| Tool | Pros | Cons | Verdict |
|---|---|---|---|
| Confluence | Familiar, structured | Poor dev integration, outdated model | ❌ Outgrown |
| Read the Docs | Simple, Sphinx-based, versioning support | Python-focused, limited customization | ⚠ Too rigid |
| MkDocs | Lightweight, good search, fast | Less UI flexibility | ⚠ Great but limited for branding |
| Hugo | Very fast, flexible | Requires more setup, not docs-first | ⚠ Too generic |
| Docusaurus | MDX, versioning, React components, fast CI/CD integration | Initial setup heavier | ✅ Perfect balance |
We chose Docusaurus because it aligned with how we already worked: Git, Markdown, pull requests, CI/CD, and reusable components.
7. Understanding Docusaurus (for those new to it)
At its core, Docusaurus is a static site generator designed specifically for documentation.
It combines Markdown with React — giving you the simplicity of writing content in .md files and the flexibility of building custom UI when needed.
Key features that mattered for us:
- Versioning: Tie docs to releases — a feature Confluence never had.
- MDX support: Mix Markdown with React components for rich documentation (feels funky, but kind of cool).
- Search: Fast, extensible, works out of the box (Algolia or Typesense).
- Custom plugins: Integrate linters, search, CI checks.
- Speed: Our site loads fast — customers notice that.
- Familiar workflow: Pull requests, code review, previews — like any other repo.
For our engineers, writing docs started feeling less like "extra work" and more like writing code. Some even said that documentation started to be fun.
8. Our Docusaurus Documentation Platform
Instead of treating documentation as a collection of pages, we built a documentation platform on top of Docusaurus.
The goal was simple: any team should be able to start migrating from Confluence to Docs-as-Code without needing hand-holding.
Our Docusaurus came with structure, guidance, and guardrails that made contribution predictable and safe.
What our Docusaurus setup provides
Our documentation platform includes:
Clear structure and navigation: A predefined information architecture so teams don’t invent their own page trees.
Built-in tutorials: Step-by-step guides that explain how to migrate content from Confluence, how to structure pages, editing guidelines, and how to use MDX components correctly.
Guardrails by default: ESLint & Prettier for consistent formatting
Vale for terminology, style, and writing quality
CI checks that prevent broken builds or low-quality content from being merged
Reusable MDX components: Components like , , and warnings for deprecations helped teams present information consistently without custom markup.
Search and discoverability: Fast, global search made content immediately usable for customers.
CI/CD with preview environments: Every pull request gets a preview deployment so contributors can see exactly what they are about to publish.
Theming and branding: Documentation looks and feels like part of the platform, not an afterthought.
The result: teams could migrate their content incrementally, at their own pace, without breaking anything — and without needing a central documentation team to mediate every change.
Sharing is Caring!
Later in this post, we'll share a generic version of this setup — a reusable Docusaurus scaffold based on what we built internally. It includes the same structure, guardrails, and conventions, so your team can adopt Docs-as-Code without starting from scratch
9. The First Migration
We started small: one service, one team.
We rewrote only the most accessed and most broken pages. Minimal navigation. Strict linting. Then we shipped.
Then we shipped it.
The response surprised us.
- Customers noticed the speed
- Engineers fixed docs in the same PR as code
- Reviews made documentation visible again
Momentum follows. What used to live across multiple Confluence spaces consolidated into a single, structured documentation system.
10. Documentation as an Enabled Ecosystem
The biggest shift wasn't technical — it was systemic.
Documentation became a shared interface between platform teams, SREs, portal developers, and customers.
- It enabled self-service instead of support load
- It reduced onboarding friction
- It made platform capabilities — and gaps — visible and discoverable
- It allowed feedback to flow directly into improvements
In other words: documentation stopped being static knowledge and became part of the platform ecosystem itself.
In hindsight, this aligns closely with what platform engineering maturity models describe as an enabled ecosystem: teams don't just consume the platform — they actively shape it.
11. What Surprised Us Most
When we moved to Docs as Code, we expected better structure.
What we didn't expect was how it would bring teams together.
SRE engineers and portal developers now speak the same documentation language. Platform teams see their work reflected directly in docs. Customers trust what they read again.
The act of writing and reviewing together created something Confluence never could: a shared documentation identity.
12. Lessons Learned Along the Way
Start with a narrative, not a tool.
Align teams on why you're doing this.Don't migrate everything.
Migrate the docs that matter most first. Cut the old and ugly and don't be afraid to rewrite stuffMake contribution effortless.
A good scaffold lowers the barrier.Automate quality.
Vale, CI, formatting — make good docs the default, not the exception.Documentation is never done.
Build habits, not one-time migrations.Customers are collaborators.
Give them a way to contribute — it builds trust.
13. Why We're Sharing Our Scaffold
This isn't just a success story. It's also a pattern other teams can use.
We’re making our internal scaffold available as a private starter repo: https://github.com/VincentvonBueren/erfa-docusaurus-demo/
You can fork it, clone it, or just learn from how we structured it.
We don't believe great documentation should be an afterthought.
We believe it should be a first-class citizen of every cloud platform.
14. The Moral of the Story
Our journey began with a customer pointing out an outdated page.
It ended with documentation that moves at the speed of our platform.
Docusaurus wasn't the hero of this story.
It was the vehicle that helped us tell a new one.
If your team is still fighting Confluence sprawl, don't start with a tool.
Start with a narrative. Then give it the right structure. And watch your docs come alive.