Confluence Best Practices for Engineering Teams in 2026

Why Most Confluence Instances Become a Graveyard

Confluence is one of the most powerful knowledge-management tools available — and one of the most commonly misused. The typical pattern: a team sets it up, dumps documents into it for six months, then slowly stops using it because nobody can find anything and half the pages are out of date.

The problem isn't Confluence. It's that most teams never design their information architecture intentionally. They just start creating pages.

This guide covers the practices that separate high-functioning Confluence instances from documentation graveyards.

1. Design Your Space Structure Before You Create Anything

The biggest mistake teams make is creating pages immediately without deciding on a space structure first. Spaces are the top-level containers in Confluence — think of them like filing cabinets. Get this wrong and everything else suffers.

Recommended Space Structure for Engineering Teams

• ▹Engineering Hub — Central space for all engineering: architecture decisions, onboarding, runbooks, RFCs
• ▹Product — Product specs, PRDs, roadmap documentation
• ▹Team spaces — One per team (Frontend, Backend, Platform, Data) for work-in-progress content
• ▹Projects — One space per major project or initiative (archive when complete)

Avoid creating too many spaces. It's better to have five well-organised spaces than twenty half-empty ones.

What NOT to put in Confluence

• ▹Real-time communication (use Slack/Teams)
• ▹Data that changes frequently (use a database or spreadsheet)
• ▹Code (use your version control system)
• ▹Meeting recordings (use a video platform)

2. Use Page Templates for Consistency

Without templates, every page looks different and contains different information. Templates enforce structure and make it dramatically faster to create new pages.

Templates Every Engineering Team Should Have

Meeting Notes Template

Date: [DATE]
Attendees: [NAMES]
Facilitator: [NAME]

## Agenda
- Item 1
- Item 2

## Discussion & Decisions
| Decision | Owner | Due Date |
|----------|-------|----------|
|          |       |          |

## Action Items
- [ ] Action item — Owner — Due date

## Next Meeting
Date:

Architecture Decision Record (ADR)

## Status
[Proposed / Accepted / Deprecated / Superseded]

## Context
What is the issue or situation that motivated this decision?

## Decision
What did we decide to do?

## Consequences
What are the positive and negative outcomes of this decision?

## Alternatives Considered
What other options did we evaluate?

Runbook Template

## Service Overview
What does this service do?

## On-Call Contacts
Primary: [name, Slack handle]
Escalation: [name, contact]

## Common Incidents
### [Incident Type]
Symptoms:
Diagnosis steps:
Resolution:

## Dashboards & Monitoring
- [Link to dashboard]

## Runbook Last Updated
Date: [DATE] — Updated by: [NAME]

To create templates in Confluence: go to Space Settings → Templates → Create template. Once saved, any page in that space can be created from the template.

3. Establish a Page Ownership Model

Every page should have an owner. Without ownership, pages go stale with no one accountable for keeping them accurate.

How to Implement Page Ownership

• ▹Use Confluence's Page Properties macro to add a metadata table to key pages with: Owner, Last Reviewed, Next Review Date, Status (Current / Needs Update / Archived)
• ▹Set a quarterly reminder (calendar invite or Jira recurring task) for each owner to review their pages
• ▹Label pages with needs-review when they're flagged as potentially stale

The 6-Month Archive Rule

Any page that hasn't been updated in 6 months and has no scheduled review should be either: updated and given a new review date, or moved to an Archive space. Don't delete — archive. You might need it for historical reference.

4. Get Permissions Right From the Start

Confluence permissions are one of the most common sources of frustration. Teams either make everything public (leading to accidental edits) or lock everything down (leading to people working around the system).

Recommended Permission Model

Key Permission Rules

• ▹Never give anonymous users access unless the space is intentionally public-facing
• ▹Use groups, not individuals — when someone leaves the company, removing them from one group removes their access everywhere
• ▹Restrict page deletion to space admins — recovering deleted pages is painful

5. Use Labels Consistently

Labels are Confluence's tagging system. Used well, they make content discoverable. Used inconsistently, they're useless.

Label Conventions to Adopt

• ▹Status labels: draft, reviewed, approved, archived, needs-review
• ▹Content type labels: runbook, adr, onboarding, incident-report, rfc
• ▹Team labels: frontend, backend, platform, data, devops

Create a single page in your Engineering Hub called "Label Glossary" that lists all approved labels and their meanings. Link to it from your Confluence onboarding page.

6. Integrate Confluence With Jira

If you're using both Jira and Confluence (both Atlassian products), integrating them properly multiplies the value of both tools.

High-Value Integrations

Link Jira issues to Confluence pages: In any Jira issue, use the "Link" button to attach a Confluence spec or runbook. Team members can navigate directly from ticket to documentation.

Embed Jira issue lists in Confluence: Use the Jira Issues macro to embed a live JQL query result in a Confluence page. Example: embed all open bugs for a sprint directly in the sprint planning page.

Confluence Product Requirements → Jira Epics: When a PRD is approved in Confluence, create the corresponding Jira Epic directly from the page using the Create Jira Issue macro.

7. Run a Quarterly Confluence Audit

Without regular maintenance, Confluence degrades. Schedule a quarterly audit covering:

• ▹[ ] Pages with no owner assigned
• ▹[ ] Pages not updated in 6+ months
• ▹[ ] Spaces with fewer than 5 pages (consolidate or delete)
• ▹[ ] Duplicate or near-duplicate pages on the same topic
• ▹[ ] Broken links or macros
• ▹[ ] Unused templates
• ▹[ ] Permission review — are the right people in the right groups?

The audit takes 2–3 hours per quarter for a team of 20–50 people and pays for itself in avoided confusion and faster onboarding.

Common Confluence Mistakes to Avoid

Mistake 1: Using Confluence as a chat tool — Pages are for persistent reference content, not quick messages. Use Slack for that.

Mistake 2: Nesting pages too deeply — More than 3 levels deep and people stop browsing. Flatten your hierarchy.

Mistake 3: No onboarding page for new hires — Every new engineer should be pointed to a "Start here" page that links to all the key spaces and explains the structure.

Mistake 4: Letting Home pages go stale — The space home page is what people see first. If it has outdated content, it signals that the whole space is unreliable.

Mistake 5: Not using page restrictions for sensitive content — Some pages (salary bands, performance reviews, security incident post-mortems) should be restricted. Don't rely on "people just knowing" not to look.

Want a Confluence Setup That Actually Works?

We set up and restructure Confluence instances for engineering teams every week. If your wiki has become a graveyard, we can audit it, redesign the information architecture, and train your team on the practices above.

Book a free Confluence audit →