How to Use Confluence as a Developer Wiki

Confluence has a reputation problem with developers. The editor feels heavy, markdown isn't how pages are stored, half the team wants docs in GitHub, and the other half uses Notion. Without care, Confluence ends up as a graveyard of stale meeting notes.

That reputation is partly deserved and partly outdated. There are cases where Confluence is the right choice for a developer wiki, and when it is, there's a way to set it up so developers will actually use it and keep it current.

---

When Confluence makes sense for developers

Don't reach for Confluence just because your company already pays for it. It's a good fit when these are true:

Your team already uses Jira. The Jira and Confluence integration is useful day to day: linking a runbook to an incident, embedding a sprint's issues in a planning page, referencing an ADR from an epic. If your team lives in Jira, having docs one click away is real value.

You need docs tied to project history. GitHub wikis sit apart from non-code work. Notion now offers a one-way Jira sync that pulls work items into a Notion database (on its Business and Enterprise plans), which helps for tracking, but Confluence links pages, epics, releases and issues in both directions inside the same Atlassian site.

Compliance or audit requirements exist. Page history with authors and timestamps, page and space restrictions, and admin controls come built in.

Your organization is big enough that discoverability matters. In a 10-person team everyone knows where docs live. In a 200-person engineering org, one searchable Confluence site beats dozens of repo wikis and scattered workspaces.

If none of these apply, Notion or a docs-as-code setup (markdown in a repo, rendered with something like Docusaurus) is probably the better call. For a fuller comparison, see Confluence vs Notion for engineering teams.

---

How to structure a developer wiki in Confluence

The two common failure modes are opposites: everything dumped flat into one space (300 pages at the root is a search problem), or five levels of nesting nobody can navigate.

Organize around teams or services, not projects. Projects end; teams and services last. One space per team or service domain gives every page a clear owner and a natural home.

A practical structure for an engineering space:

Engineering (space root)
├── Onboarding
│   ├── New Engineer Setup
│   ├── Development Environment
│   ├── Access & Permissions Request
│   └── First Week Checklist
├── Architecture
│   ├── System Overview
│   ├── RFCs
│   ├── Architecture Decision Records (ADRs)
│   │   ├── ADR-001: Use PostgreSQL for primary storage
│   │   ├── ADR-002: Adopt event-driven architecture
│   │   └── ADR-003: ...
│   └── Data Flow Diagrams
├── Services
│   ├── auth-service
│   │   ├── Overview & Runbook
│   │   ├── API Reference
│   │   └── Known Issues
│   └── payments-service
│       └── ...
├── Runbooks
│   ├── Incident Response
│   ├── Database Failover
│   ├── Deployment Rollback
│   └── On-Call Handoff
├── Incident Postmortems
│   ├── 2026-04-12 Payment Processing Outage
│   └── 2026-03-07 Auth Service Latency Spike
└── Release Notes
    └── (one page per release or sprint)

A few principles behind it:

• Runbooks get their own section, not buried under individual services. When something breaks at 2am, nobody should need to know which service owns the runbook.
• Postmortems are first-class content. Don't hide them or let them expire. They're some of the most valuable knowledge a team produces.
• Services share a lightweight, consistent structure: overview, runbook and API reference at minimum. For API pages, see how to document APIs in Confluence.

---

Templates for the four core engineering docs

Engineers skip writing docs when they have to invent the structure. Create these as Confluence templates in your space so the blank page is already half filled:

Template	When to use it	Sections
RFC	Proposing a significant change before building it	Background, Proposal, Alternatives considered, Open questions, Decision
ADR	Recording a decision after it's made	Context, Decision, Status, Consequences
Runbook	Operational procedures	Purpose, When to use, Prerequisites, Steps, Rollback, Escalation
Postmortem	Learning from an incident	Timeline, Root cause, Contributing factors, Action items

Two notes. ADRs capture the why at a point in time, so they're written once and rarely edited; supersede them with a new ADR rather than rewriting history. And a runbook without a rollback section isn't finished.

---

Making Confluence dev-friendly

The editor is where most developers give up. A few things remove that friction:

Write in markdown where it helps. Markdown Macro+ for Confluence lets you write sections of a page in markdown, with fenced code blocks, syntax highlighting, tables and task lists that look the way they do in a README. Mix it with native Confluence content: use the editor for layout and Confluence macros, and the markdown macro for content-heavy technical sections.

Bring existing docs in. If your docs already live as .md files, Markdown Importer for Confluence imports individual files or a ZIP (folders become a page tree, images come along). It doesn't pull from a repository URL on its own, but its REST API lets a CI job push changed files on every merge. See how to sync GitHub docs to Confluence automatically.

Show code, not prose. If you're documenting a deploy, show the commands; if you're documenting config, show the file. Use code blocks and always set the language. Our guide to inline code and code blocks in Confluence covers the shortcuts.

Use labels and page properties. Consistent labels (runbook, adr, postmortem, service-auth) give you free filtering. The Page Properties and Page Properties Report macros turn child pages into an auto-updating table, which works well for an ADR index or a service catalog with an owner column.

Link Jira on purpose. Link RFCs and specs from the epics that implement them. Reference ADRs from every epic they affect. If you use Jira Service Management, link runbooks from the relevant request types so on-call engineers get them in context.

---

Keeping it current

Stale docs are worse than missing ones in one way: they create false confidence. A runbook that worked 18 months ago will mislead the on-call engineer who follows it today. These habits keep a wiki trustworthy:

• Give every page an owner, and show it in a page properties table. Pages without owners decay by default.
• Add "Last verified: date" to runbooks and architecture pages. Readers can judge how much to trust the page, and an old date is a prompt to review it.
• Update runbooks right after incidents. If you followed a runbook during an incident, fix it while the details are fresh.
• Make docs part of done. Add "relevant documentation updated" to your Definition of Done or PR template for changes that affect behavior, config or process.
• Run a quarterly cleanup. Half a day to review existing pages, not write new ones: archive what's obsolete, fix broken links, refresh verified dates.

The onboarding test

Every six months, give a new engineer 30 minutes and only Confluence to answer:

1. How do I set up my local development environment?
2. Where does service X store its data?
3. Who do I contact if the payment pipeline is down?
4. Why did we choose our message queue?
5. How do I deploy to staging?

If they can't, the structure isn't working, even if the information exists somewhere. Use the gaps to plan documentation work, not to assign blame.

---

What not to do

Don't put everything in Confluence. Chat belongs in Slack, code review belongs in GitHub, and tasks belong in Jira. Confluence is for stable, findable reference material: runbooks, specs, decisions and onboarding.

Don't use Jira tickets as documentation. Tickets capture decisions in the context of a sprint, not in a form anyone can navigate six months later. "It's all in the tickets" usually means "we have no documentation."

Don't write giant pages. A 10,000-word page that should be five linked pages is common and painful. If you scroll for more than two screens to find something, split it.

---

An honest assessment

Confluence is a tradeoff. The editor is slower than a markdown file in VS Code, search isn't great for code snippets, and without someone reviewing and archiving pages it degrades.

What it does well is stable, findable reference documentation for teams in larger organizations that already run Jira. If that's you, set up a clear structure from day one, add templates, get markdown support in place so developers don't fight the editor, and keep the scope tight. A small, well-maintained space beats a large, neglected one.

---

Questions? Reach out via our support portal.