confluence-best-practices — use Confluence leanly, structure content sensibly, write it readably

Judgment layer for an agent that acts on Confluence (creates, organises, governs content) and, second, for a human authoring pages — the same structure serves both: what makes a page scannable makes it retrievable.

Instance-agnostic: discover the org's space taxonomy, conventions and working language; never assume them. Defaults are Confluence Data Center 10.2 / 9.2 LTS, with the Cloud counterpart noted inline.

How the work gets done (execution layer)

An agent here acts through content-level REST/CQL — directly, or via an MCP server (e.g. mcp-atlassian), or by handing the user UI steps. The boundary that determines what to do versus what to advise is the same on every instance:

• What an agent DOES directly (content level, no admin rights): create/update/move/delete pages and blog posts; re-parent a page; add/remove labels; add comments; set/read page restrictions; run CQL searches; read the page tree; build a Page Properties Report governance dashboard. All of this is POST/PUT/GET against /rest/api/content (DC) or /wiki/api/v2/pages (Cloud).
• What an agent ADVISES the human to do (admin / global config — not doable at content level): create a space and set its permission scheme; set default space permissions; restrict who can create spaces; build templates/blueprints; set the indexing language; configure retention rules; install apps. For these, hand the user the exact, minimal steps (the reference files carry the DC click-paths) rather than attempting them via a tool.
• Done = every write read back. Re-fetch each created/updated/moved page with ?expand=ancestors,version,metadata.labels and confirm the intended parent, the full label set and a version one higher than before (1 for a new page); re-read every changed restriction via /content/{id}/restriction. Every admin-lane item reaches the user as numbered steps. A write not read back is not done.

So a good response usually = (a) the correct content action taken via REST/CQL, plus (b) a crisp, copy-pasteable recommendation for anything that needs an admin. This skill decides what and how to structure content; it is not a manual for any one tool — for setting up the mcp-atlassian server itself, that's the jira-confluence-mcp sibling skill.

The prime directive

Most Confluence dread is a usage problem, not a tool problem. The wikis that work are the ones with the least unmanaged sprawl. So, every time:

1. Lean by default. The right answer is almost always fewer and shallower — fewer spaces, shallower page trees, fewer macros, one home per page, less duplication. Creating content is frictionless; retiring it takes a deliberate act, so a wiki only grows unless someone prunes. When in doubt, recommend consolidating, archiving, or removing.
2. Adapt to the org, never impose. Organisations legitimately organise spaces by team, by project, by function, or by product — all valid. Discover their space roles, label vocabulary, and working language, and reason in their terms. Describe structure by role ("a space is a container + permission boundary; a page is content"), then map to what they actually call it.
3. Readability is a first-class outcome — and it doubles as agent-retrievability. Answer first, one page = one purpose, the answer in text (not buried in a screenshot) — the same moves serve the human reader and the RAG/agent retriever.
4. Non-English is fully normal. Never auto-translate or rewrite a user's content; anchor logic on keys, not display strings (Discover before advising).
5. Diagnose before prescribing. Name the specific dread — can't find it / it's rotting / it's duplicated / it's hidden / it's unreadable — trace it to a cause, then propose the smallest fix. Don't redesign the whole space when one inherited restriction is the problem.

Cloud vs Data Center — speak the right dialect (read this first)

Most "new Confluence" coverage describes Cloud, and the DC gap is wide enough that wrong-dialect advice is unusable. This skill is DC-first, Cloud-compatible — know both columns. The single biggest trap is the editor and content format.

DC versions, Java floors, EOL dates and the DC sunset live in references/cloud-vs-dc.md — read the instance's version before any version-gated advice; this skill is about using today's Confluence well, not migrating.

To tell which applies, check the REST base path: /wiki/api/v2/... works → Cloud; only /rest/api/content → DC. Full feature-split matrix in `references/cloud-vs-dc.md`.

Information architecture — space, page, or child? (by role, not by name)

The primitives and the placement decision:

   Space            CONTAINER + permission/ownership boundary — its own homepage, sidebar, admin
     │
   Page             a UNIT OF CONTENT (one purpose)
     │
   Child page       a page with exactly ONE parent (the tree is single-parent)

The decision heuristic:

• New SPACE only when the content has a distinct owning team/project, needs its own permission scheme, and should stand alone in the Space Directory. A space is heavyweight (permissions + homepage + admin), so "a space per tiny project" is the dominant clutter anti-pattern. Sharpest tie-breaker: don't create a space just to hide a few pages — use page restrictions instead (they're more granular than space permissions).
• PAGE in an existing space is the lean default for most new content.
• CHILD page only when it logically belongs under one specific parent. The tree is single-parent — if content belongs to several categories, label it; never duplicate it into two parents.

Describe by role, map to the org's names. DC's space types (team / knowledge-base / documentation / personal) are just starter templates that "don't really have much effect once created." So reason in roles — home, project-workspace, reference-KB, personal-scratch, department-intranet, meeting-notes — detect which role a space plays, and adapt to whatever the org named it. The one near-universal rule is consistency by type: spaces of the same role should be named alike and share a top-level structure.

Tree shape: shallow. Cap depth at ~3, maybe 4 levels — Atlassian ships an official "too many nesting levels" health check confirming deep trees have a real performance cost (and deep pages get neglected, "out of sight, out of mind"). Every space needs a homepage that orients and routes (overview + key links + label indexes). Re-home orphan pages (no parent, no inbound links).

Labels = cross-cutting; tree = containment (the analogue of "hierarchy rolls up, links don't"): the tree answers "where does this live" (one place); labels answer "what is this about" (many facets, and they reach across spaces). The same split exists for spaces — space categories are just labels on spaces.

Full treatment (the space-vs-page checklist, role table, folders caveat, orphan/depth fixes): `references/information-architecture.md`.

Discover before advising (and stay language-safe)

A recommendation that hardcodes a space name, a page title, or an English label is wrong on the next instance — and doubly wrong on a non-English one. Discover the org's real values, and anchor logic on language-independent keys.

The rules that prevent localized-content bugs:

1. Anchor on keys, not display strings. The space key, numeric content ID, label text, CQL field names, and content-type survive a localized UI and per-user display language. The space name and page title do not — never use them as durable lookup keys.
2. Write in the instance's working language. Set summaries/titles/labels in that language; never auto-translate. (Labels force lowercase and disallow spaces, so a multi-word non-English tag like "Vertrieb Nord" must become vertrieb-nord.)

The full discovery recipe, the act-vs-advise mapping, programmatic-write safety (storage format, the unique-title idempotency key, version-increment/409, not clobbering human formatting), CQL governance recipes, and the Cloud-vs-DC execution branches are the operational heart of this skill: `references/agent-execution-and-discovery.md`.

Lean content & lifecycle — fighting the "graveyard"

The named dread is "Confluence is where documentation goes to die." The mechanism is structural: creation is free, retirement is manual, so content rots silently (there's no test that goes red when a runbook references a dead service). De-bloat with these levers, highest-leverage first:

1. Make ownership + staleness visible — the agent-buildable governance dashboard. Put a Page Properties macro (Owner / Review-Date / Status) on content pages + a shared label, then a Page Properties Report index page keyed on that label. This is the single highest-leverage no-admin pattern — the agent can build it entirely at content level. (Caps: 3,000 pages / 60 labels, tunable.)
2. Find rot with CQL. type=page AND lastmodified < startOfYear() (scope by space/owner), plus "no labels" and duplicate-title sweeps. Agent-actionable.
3. Kill duplication with transclusion, not copy-paste. Excerpt + Excerpt Include (a snippet) and Include Page (a whole page) keep one canonical source; edit once, every reference updates.
4. Prune in the right order: trash + version-retention rules → move obsolete pages to an archive space → archive that space → delete (with an XML export) only to reclaim index/DB.
5. The DC lifecycle gotcha: DC has NO native page-level archiving (Cloud does). Space archiving excludes a space from search/Directory but keeps it in the index (a relevance lever, not a perf one). To "archive a page" on DC, move it into a dedicated archive space — and note that pages cannot be moved into an already-archived space (flip it to Current first).
6. The one hard guardrail: < 8,000 spaces is optimal on DC (8–10k approaching, >10k degraded — driven by permission checks). Pages are not a primary perf axis; but very large, macro/table-heavy pages break the editor — split them.

Mechanics (retention rules, archive workaround, the dashboard storage format, performance numbers): `references/lean-content-and-lifecycle.md`.

Findability — search, labels, titles, navigation

"I can't find anything" is the #1 complaint — and it's the content, not the engine ("Confluence search isn't that bad; what's bad is the data fed into it"). Fix the corpus:

• Titles are the cheapest lever — and page titles must be unique within a space, so make them distinctive and consistently prefixed (RUNBOOK – Payments – Failover), never generic ("Notes", "Meeting").
• Labels as a small controlled vocabulary (lowercase, no spaces, singular), pre-loaded into templates so pages are born tagged.
• Navigation beats search for known content: shallow well-named trees + a curated homepage (Children Display / label indexes) + the Space Directory.
• CQL is the agent's discovery surface (text, title, label, space, type, ancestor/parent, lastmodified, creator).
• Search caveats to set expectations: whole-word/stemmed by default; stop-words stripped even in quotes; special chars stripped (DOC-8510 → doc AND 8510); no leading wildcard; CJK uses bigram tokenization with exact-search off; umlaut+wildcard is broken (but plain-term accent folding works). OpenSearch (DC, opt-in since 9.0) is faster, not more relevant.

Full CQL field reference, label governance, and the indexing/language caveats: `references/findability-and-search.md`.

Authoring & readability — make pages people (and agents) can read

The second pillar. The same structure serves human scanning and machine retrieval:

• The page title is the H1, so body content starts at H2 → H3 (don't skip levels; cap ~H3/H4). A Table of Contents macro pays off on long pages only.
• Answer first (BLUF / inverted pyramid — most readers scan, not read). Open with a one-line summary (an Info panel), write topic-sentence-first paragraphs, chunk into short sections.
• One page = one purpose (Diátaxis: tutorial / how-to / reference / explanation — mixing types is the root of most doc problems). Plus ADRs, runbooks, meeting notes.
• Macros earn their place. Info/note/warning panels, Expand, Excerpt, Children Display help; macro/table overload clutters and degrades the editor. Keep tables small (on Cloud, the new editor also limits table copy/paste — CONFCLOUD tickets do not apply to DC).
• Author for retrieval too: put the answer in text, not only in a screenshot/attachment; descriptive link text (no "click here"); labels + Page Properties for structure.
• Accessibility: alt text, descriptive links, real heading semantics, don't rely on colour alone.

The mistakes→fix table, Diátaxis mapping, macro guidance, and storage-format snippets: `references/authoring-and-readability.md`.

Permissions & governance, and the Jira boundary

• Three layers: global (can-create-spaces, admin) → space (view/add/edit) → page restrictions. Space permissions are additive; page restrictions subtract — they narrow, never grant (a restriction can deny a user with space-View, but can't give View to someone who lacks it).
• View restrictions cascade to child pages; edit restrictions do NOT. This makes *an inherited view-restriction on an ancestor the #1 cause of "I can't find/see the page" — the page silently drops from search and the tree. Diagnose by walking up* the tree.
• Open by default. Atlassian's own stance: "keep Confluence as open as possible." Restriction is the justified exception (HR/legal/security), not the posture; over-restriction creates silos.
• Governance levers (advise-the-human): restrict `Create Space(s)` to a champions group (whoever creates a space becomes its admin → sprawl); set default new-space permissions; use groups, not individuals.
• The Jira boundary: Confluence = durable knowledge (requirements, decisions, design docs, runbooks, the how-and-why); Jira = trackable work with status. Link them with the permission-aware Jira Issues macro (live status on the page). Note Smart Links are Cloud-only.

Permission mechanics, the "can't see the page" playbook, and integration: `references/permissions-and-governance.md`.

Diagnose-the-dread playbook

Match the symptom, name the cause, apply the smallest fix:

Anti-patterns (call these out)

1. A space per tiny project — use a page; reserve spaces for real audience/permission boundaries.
2. Duplicating a page under two parents — label it; the tree is single-parent.
3. Deep page trees (5+ levels) — cap at 3–4; promote subtrees to siblings or a new space.
4. Pages with no owner and no review date — invisible rot; add Page Properties + a Report dashboard.
5. Copy-pasting shared content — use Excerpt/Include; one canonical source.
6. Over-restriction — silos and "can't find it"; open by default, restrict only what's genuinely confidential.
7. Generic titles ("Notes", "Meeting") — collide (unique-per-space) and rank poorly; be descriptive.
8. Macro/table overload — clutters and lags the editor; every macro must earn its place.
9. Answers locked in screenshots/attachments — unreadable to search and to agents; put the answer in text.
10. Auto-translating or "correcting" non-English content — never; it's normal, preserve it, anchor on keys.
11. Treating ADF as the Confluence write format — it's Jira-Cloud; Confluence writes are storage format on both Cloud and DC.
12. Bulk-deleting a CQL result set (e.g. every lastmodified hit) — old ≠ unused: date-stale pages include homepages, templates, policies, Include/Excerpt sources and parents of fresh pages, and a retention rule can purge the trash for good. Do not write the unattended delete loop. Deliver instead: read-only inventory CSV → per-space owner review → move approved pages to an archive space. Deletion is a separate, later run — only after an XML export of the affected spaces exists and the owner signs off.

What to read next