DEV Community: Vincent von Büren

From Rot to Rhythm: How We Rebuilt Our Documentation Culture with Docusaurus

Vincent von Büren — Tue, 19 May 2026 06:21:49 +0000

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 stuff
Make 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.

That Time We Found a Service Account Token in my Log Files

Vincent von Büren — Thu, 04 Sep 2025 07:59:04 +0000

⚠️ Disclaimer
This article assumes you're already somewhat familiar with Kubernetes concepts (Pods, ServiceAccounts) and the basics of JSON Web Tokens (JWTs).

It was a Tuesday.

Nothing special - just your average day as a platform engineer. My team's notifications were mercifully quiet, and I thought, "Perfect, I can finally clean up that old Helm chart that's been bothering me."

I opened the repo of the underlying image written in Go to double-check the config before merging.

Before I even got far, a colleague — Martin Odermatt — pinged me:

“You might want to take a look at this…”

He had spotted something concerning in the code:

log.Println("SA Token:", token)

Wait. What?

A debug statement. Still in production code. Logging an actual Kubernetes ServiceAccount token. Not cool...

I paused. My heart rate didn’t. Curious but mostly horrified, I took the token Martin had found and decoded the payload in my shell:

{
"iss": "https://kubernetes.default.svc.cluster.local",
"kubernetes.io/serviceaccount/namespace": "payments",
"kubernetes.io/serviceaccount/secret.name": "payments-token-6gh49",
"kubernetes.io/serviceaccount/service-account.name": "payments-sa",
"kubernetes.io/serviceaccount/service-account.uid": "f9a2c144-11b3-4eb0-9f30-3c2a5063e2e7",
"aud": "https://kubernetes.default.svc.cluster.local",
"sub": "system:serviceaccount:payments:payments-sa",
"exp": 1788201600,   // Sat, 01 Aug 2026 00:00:00 GMT
"iat": 1756665600    // Fri, 01 Aug 2025 00:00:00 GMT
}

Default audience claim. A 1-year expiry.

As we dug deeper, Martin Odermatt pointed out the underlying issue: this was a legacy ServiceAccount token, and we should be using projected tokens instead.

This "bad boy" wasn't just a dev leftover - it was a high-privilege token with zero constraints floating around in plaintext logs!

What This Article Covers

In this post, I'll guide you through:

The inner workings of Vault authentication with JWT and Kubernetes methods
What Kubernetes ServiceAccounts and their tokens are, and how they’re (mis)used
How projected ServiceAccount tokens fix many of the hidden dangers of older token behavior
Why you should start adopting token projection and Vault integration today

We'll cover real-world use cases, implementation tips, and common pitfalls - so you don't end up like I did, staring at a:

log.Println("SA token:", token)

...and wondering how close you just came to a security incident.

Why This Matters

To really understand why that log statement gave me chills, we need to unpack a few core concepts:

What is a JWT?
How do Kubernetes ServiceAccounts and their tokens work?
And what role do these tokens play in authenticating to systems like Vault?

Let's start with the fundamentals.

What Is a JWT?

If you've been around authentication systems long enough, you've probably seen one of these beasts:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

This is a JSON Web Token (short: JWT).

It's a compact, URL-safe format for representing claims between two parties. They're used everywhere: web apps, APIs, and yes — inside your Kubernetes cluster.

A JWT consists of three parts:

Header – declares the algorithm used to sign the token (e.g. RS256)
Payload – contains the claims (who you are, what you're allowed to do, etc.)
Signature – a cryptographic seal that verifies the payload hasn't been tampered with

Claims are the heart of a JWT — key-value pairs that describe who the token refers to and what it can be used for.

They can be:

Standard claims defined by the spec (e.g., iss, sub, exp, aud)
Custom claims added by the issuer for domain-specific needs

Closer Look at `aud`

The audience (aud) claim tells who the token is meant for. Think of it as the intended recipient.

Example: Imagine a Coldplay concert ticket. It says valid for Stadium X on 01-09-2025. You can't take the same ticket and use it at Stadium Y — they'll reject it (...trust me, I tried).

A JWT works the same way:

If the token has "aud": "https://kubernetes.default.svc", then only the Kubernetes API server should accept it.
If some other service receives that token, the aud won't match and the token must be rejected.

Without this check, a token could be misused anywhere that trusts the signing key. With aud, it's scoped to the right system.

Kubernetes and ServiceAccounts

Kubernetes is an open-source platform that orchestrates containers at scale. At its heart is the Pod — the smallest deployable unit.

But every pod needs an identity. That's where ServiceAccounts come in.

ServiceAccounts 101

Every Pod references a ServiceAccount (default if none is set), but a token is only mounted if enabled
Kubernetes mounts the identity at:

/var/run/secrets/kubernetes.io/serviceaccount/token

That token is a JWT, signed by the Kubernetes control plane
It lets the pod authenticate with the API server — and sometimes even external systems like Vault

The Catch

Until recently, these tokens came with dangerous defaults:

Long-lived (often valid for a year)
Previous to Kubernetes v1.24, there was no default audience set (https://kubernetes.default.svc)
Automatically mounted into every pod, even if unused

Enter Vault: The Gatekeeper of Secrets

HashiCorp Vault is your cluster’s paranoid librarian:
it stores API keys, certs, passwords — and only hands them out when it's sure you should have them.

How? Authentication methods.

Vault Authentication Methods

Username & password
AppRole
LDAP
Kubernetes
JWT

Let's zoom into the last two.

Kubernetes Auth Method

Pod sends its mounted ServiceAccount token to Vault
Vault validates it against the Kubernetes API
If valid, Vault maps it to a policy

This is simple and works well when Vault runs inside the cluster.

JWT Auth Method

Vault verifies the JWT itself (signature, claims, expiration)
No need for Kubernetes API access
More portable

Rule of thumb:

Use Kubernetes if Vault runs inside your cluster and simplicity matters
Use JWT if you want portability, stronger boundaries, and flexibility

Projected Tokens: Because It's 2025

Old tokens were static and long-lived — exactly what we were looking at here. As Martin pointed out during the investigation, projected tokens are designed to fix this entire class of problems.

Instead of mounting a one-year token into every pod, Kubernetes can now generate short-lived, audience-bound tokens on demand.

What You Get

Short TTL (e.g. 10 minutes)
Audience restrictions (aud: vault)
Automatic rotation by kubelet
No automatic mounting into pods

Example Pod with Projected Token

apiVersion: v1
kind: Pod
metadata:
  name: projected-token-test-pod
  namespace: demo
spec:
  serviceAccountName: projected-auth-sa
  containers:
    - name: projected-auth-test
      image: demo/vault-curl:latest
      command: ["sleep", "3600"]
      volumeMounts:
        - name: token
          mountPath: /var/run/secrets/projected
          readOnly: true
  volumes:
    - name: token
      projected:
        sources:
          - serviceAccountToken:
              path: token
              expirationSeconds: 600
              audience: vault

Why Vault Loves This

Vault's JWT auth method is tailor-made for projected tokens:

It parses and verifies the JWT signature (via a configured PEM key or JWKS endpoint)
Validates all claims (aud, sub, exp, iss) locally
Issues secrets only if every check passes

Minimal dependencies. Strong claim validation. Secure, verifiable checks.

Back to the Log

Imagine you stumble upon this in a Go app:

log.Println("Auth Token:", token)

Old world: a one-year, cluster-wide token with no audience. A time bomb.
New world: a 10-minute token, scoped to Vault, rotating automatically.

It's still bad to log tokens — but at least it's not catastrophic.

Try It Yourself: Vault + K8s AuthN Lab

I've built a hands-on demo repo where you can test this locally with KIND (Kubernetes in Docker) and Vault Helm charts:

👉 GitHub: VincentvonBueren/erfa-projected-sa-token

What's Inside

KIND cluster with Vault
Both Kubernetes and JWT auth methods enabled
Vault policies and roles
Four demo pods:
- Kubernetes auth method
- JWT with static token
- JWT with projected token
- JWT with wrong audience (failure demo)

Final Drop 🎤

If your pods still run with default, long-lived tokens:
you’re one debug log away from giving away the keys to your cluster.

Projected tokens aren't optional. They're essential.
Adopt them today — and stop shipping security disasters.

Acknowledgment

The discovery of the exposed ServiceAccount token — and the push towards using projected tokens — came from my dear fellow engineer Martin Odermatt, whose input significantly shaped this investigation and motivated me to tell this story.