← Back to blog

Why Confluence Fails for DevOps Teams

· 4 min read · Stew Team
tech documentationconfluencedevopsSRE

Confluence is everywhere. It’s the default choice for tech documentation software at most companies. And for DevOps teams, it’s almost always the wrong choice.

This isn’t a Confluence hit piece—it’s a recognition that different documentation needs require different tools.

Where Confluence Works

Let’s be fair. Confluence excels at:

  • Product documentation — Feature specs, PRDs, design docs
  • Meeting notes — Decisions, action items, context
  • Company wikis — Policies, org charts, processes
  • Project documentation — Timelines, status updates, stakeholders

For these use cases, Confluence is fine. It’s collaborative, searchable, and familiar.

Where Confluence Fails for DevOps

Problem 1: No Execution

The fundamental issue: Confluence pages are static.

When you need to run a command, you:

  1. Find the page
  2. Scroll to the command
  3. Select the text
  4. Copy it
  5. Switch to terminal
  6. Paste it
  7. Hope it’s right

During an incident, this friction costs minutes. Minutes cost money, reputation, and sleep.

What you need: Tech documentation software that executes commands directly.

​```bash
kubectl rollout restart deployment/api -n production
​```

Click. Run. Done.

Problem 2: Rich Text Corrupts Commands

Confluence’s rich text editor is hostile to code:

What you paste:    kubectl get pods -n production
What Confluence saves: kubectl get pods —n production

Smart quotes, em-dashes, invisible characters. Commands fail silently.

What you need: Plain text Markdown that preserves characters exactly.

Problem 3: Search Is Slow

Finding the right page in Confluence:

  1. Open Confluence
  2. Wait for load
  3. Type search query
  4. Scan results
  5. Click through wrong pages
  6. Finally find the right one

At 3am, this is unacceptable.

What you need: Docs integrated with alerts. One click from the alert to the runbook.

Problem 4: No Version Control

Confluence has page history, but it’s not Git:

  • Can’t branch
  • Can’t PR
  • Can’t diff easily
  • Can’t tie doc changes to code changes

When infrastructure changes in a PR, the related docs should update in the same PR.

What you need: Docs as code. Markdown in Git.

Problem 5: No Offline Access

SSH’d into a bastion host with no browser? Confluence is unreachable.

VPN down during an incident? Confluence is unreachable.

What you need: Docs that work in a terminal.

Problem 6: Wrong Environment

Confluence doesn’t know about:

  • Your Kubernetes context
  • Your environment variables
  • Your SSH keys
  • Your current directory

Every command needs manual adjustment.

What you need: Variable injection and environment awareness.

The Confluence Workarounds (That Don’t Work)

“We’ll be disciplined”

Teams try to maintain Confluence rigorously:

  • Monthly review schedules
  • Doc owners
  • Freshness labels

It works for a quarter. Then someone leaves, priorities shift, and docs rot.

”We’ll use code blocks”

Confluence has code blocks. They help with formatting but don’t solve:

  • Execution
  • Version control
  • Environment context

Keep commands in GitHub, link from Confluence.

Now you have two places to maintain. Links break. Docs still rot.

The Alternative: Executable Tech Documentation

Modern tech documentation software for DevOps treats docs as executable artifacts:

Markdown-Native

# Restart API Service

## Check Current Status

​```bash
kubectl get pods -n production -l app=api
​```

## Restart

​```bash
kubectl rollout restart deployment/api -n production
​```

Plain text. Versionable. Portable.

Git-Integrated

git commit -m "Update API restart runbook for new namespace"

Docs change with code. Review together. Deploy together.

Executable

Each code block runs directly. No copy-paste. No terminal switching.

Environment-Aware

export NAMESPACE=${ENVIRONMENT:-production}
kubectl get pods -n $NAMESPACE

One doc works across environments.

Migration Path: Confluence to Executable Docs

You don’t have to migrate everything. Start with operational docs:

Phase 1: Identify High-Value Runbooks

Which Confluence pages do you actually use during incidents? Start there.

Phase 2: Convert to Markdown

Extract commands into Markdown files. Strip the prose. Keep what matters.

Phase 3: Store in Git

Put runbooks next to the code they operate:

service-api/
├── src/
├── kubernetes/
└── runbooks/
    ├── restart.md
    ├── scale.md
    └── troubleshoot.md

Update your alerting to point to new runbooks:

annotations:
  runbook_url: https://github.com/org/service-api/tree/main/runbooks/restart.md

Phase 5: Sunset Confluence (for Runbooks)

Keep Confluence for what it’s good at. Move runbooks to executable tools.

Stew: Tech Documentation for DevOps

Stew is built for the use cases where Confluence fails:

  • Executable — Run commands directly
  • Markdown-native — Plain text, Git-friendly
  • Works anywhere — Terminal, SSH, browser
  • Variable support — One doc, any environment

Join the waitlist and see what tech documentation software for DevOps should look like.