What Confluence documentation is and why the structure matters

Confluence is a wiki-based workspace where teams write, organize, and share documentation. Unlike a shared folder or email thread, Confluence lets you build connected pages that link to each other, track who changed what and when, and search across everything at once. The difference between good Confluence documentation and bad Confluence documentation is almost entirely about structure — how you name pages, where you nest them, and how you link them together.

Most teams that struggle with Confluence have the same problem: pages exist, but nobody can find them, and when they do find them, the information is scattered across five different places. This guide walks through the actual steps to set up a space, create pages that people will use, and organize them so they stay findable as your documentation grows.

Key Takeaways

  • Create a clear page hierarchy by using parent and child pages, with a homepage that lists what lives where and links to the main sections.
  • Name pages with the reader's question in mind, not with internal jargon — "How to reset your password" beats "Password Reset Procedures".
  • Use templates for pages that repeat the same structure, like onboarding guides or process documentation, so new pages start with the right format.
  • Link related pages to each other within the text and use the "Related Pages" macro so readers can find connected information without scrolling.
  • Assign one person to review and archive outdated pages every quarter, or documentation will fill with conflicting versions and dead links.

Setting up your space and building a homepage

A Confluence space is a container for related documentation — one for engineering, one for HR, one for sales, depending on your team's structure. When you create a space, you get a blank homepage. This homepage is the most important page you will write, because it is the only page most people will see first.

Your homepage should list the main sections of documentation and link to the page that starts each section. For example, an engineering space might have sections for "Getting Started", "How-To Guides", "Architecture", and "Troubleshooting". Under each heading, write one sentence describing what lives there, then link to the parent page for that section. Do not put the actual content on the homepage — link to it instead. This keeps the homepage scannable and makes it obvious where to look.

To create this structure, add a new child page under your homepage for each main section. Name these pages clearly: "Getting Started", "API Documentation", "Deployment Guides". Then add child pages under those. A reader should be able to start at the homepage, click once or twice, and find what they need.

Naming pages so people can find them

Page names are the first thing a reader sees in search results and in the page tree. A page named "Q3 Updates" tells you nothing. A page named "How to deploy to production" tells you exactly what is inside. Write page names as if you are answering the question someone would type into a search box.

Use consistent prefixes for pages that serve the same purpose. If you have multiple how-to guides, start each one with "How to". If you have troubleshooting pages, start them with "Troubleshooting". This makes the page tree scannable and helps readers predict what they will find. Avoid acronyms and internal jargon in page names unless your entire audience uses that term every day — "SSO configuration" is fine for an engineering team, but "How to set up single sign-on" is better if your audience includes non-technical staff.

Keep page names short enough to read in one line. If your page name is longer than ten words, you are probably trying to say too much. Break it into a shorter name and put the detail in the first paragraph of the page itself.

Writing pages that people will actually read

Confluence pages work best when they follow a consistent format. Start with a one-sentence summary of what the page covers, then add a table of contents if the page is longer than a few paragraphs. Use headings to break up the text — readers scan pages, they do not read them top to bottom.

For how-to pages, use numbered steps and include the actual names of buttons, menus, and fields. "Click Settings" is vague. "Click the Settings icon in the top right corner, then select Notifications from the left menu" tells someone exactly what to do. Include screenshots when the interface is complex or changes often — screenshots get outdated, but they are better than no visual reference at all.

For reference pages like API documentation or configuration guides, use tables to show options side by side. A table with columns for "Parameter", "Type", "Required", and "Description" is faster to scan than paragraphs. Keep examples short and real — show what actually works, not a theoretical example.

At the end of every page, add a "Related Pages" section or use Confluence's Related Pages macro. Link to pages that cover related topics or that readers might need next. This keeps readers in your documentation instead of sending them back to search.

Using templates to keep new pages consistent

If you write the same type of page repeatedly — onboarding guides, process documentation, incident reports — create a template. In Confluence, go to your space settings and create a page template. Include the headings and sections that every page of that type should have, then save it as a template.

When someone creates a new page, they can choose your template and start with the right structure already in place. This saves time and makes sure all pages of the same type are organized the same way. For example, an onboarding template might include sections for "Before You Start", "Day One", "First Week", and "First Month", with placeholder text in each section.

Review your templates every six months. If you notice people are always deleting a section or always adding the same new section, update the template. Templates should reflect how your team actually writes documentation, not how you think they should.

Linking pages and using macros to connect information

Confluence pages are most useful when they link to each other. When you mention a related topic, link to the page that covers it. Use the link tool in the editor to search for existing pages — if a page already exists, link to it instead of rewriting the information.

Use Confluence macros to embed related information without copying it. The "Related Pages" macro shows links to pages tagged with the same label. The "Include" macro lets you embed one page inside another, so if you update the included page, the change appears everywhere it is used. The "Table of Contents" macro automatically builds a clickable outline from the headings on your page.

Avoid duplicating information across pages. If the same instructions appear on two pages, you will eventually update one and forget the other. Instead, write the instructions once and link to them from both places. If you need to include the same text in multiple places, use the Include macro.

Keeping documentation current and removing outdated pages

Documentation decays. A page that was accurate six months ago might be wrong today. The only way to stop this is to assign someone to review pages on a schedule — quarterly is a good starting point. That person reads through each page, checks whether the information is still correct, and either updates it or marks it as outdated.

Confluence has a feature called "Page Properties" where you can add a custom field for "Last Reviewed" or "Status". Set a rule: if a page has not been reviewed in the last three months, add a banner to the top saying "This page may be outdated". If it has not been reviewed in six months, move it to an archive space and remove it from the main navigation.

When you find conflicting information on two pages, merge them. Keep the more complete version, update it if needed, and delete the other page. Replace the deleted page with a redirect or a note pointing readers to the correct page. This prevents readers from finding the wrong answer.

Frequently Asked Questions

Should I use labels and tags to organize pages, or should I rely on the page hierarchy?

Use both. The page hierarchy is how readers browse — it is the main navigation. Labels are how readers search. Tag pages with labels that describe what they cover: "onboarding", "api", "troubleshooting", "security". This lets someone search for all pages tagged "security" without having to know which space they live in.

What should I do if I have a page that does not fit neatly into the hierarchy?

Put it in the most relevant section and link to it from other places where readers might look for it. You can also create a "See Also" section at the bottom of related pages that points to it. Confluence search is good enough that if the page is well-written and well-linked, people will find it.

How do I handle pages that need to be updated frequently, like release notes or status pages?

Create a parent page that lists the most recent updates, with links to older versions. For example, a "Release Notes" page might list the current release at the top, then link to "Previous Releases" which contains older versions. This keeps the current information easy to find while preserving history.

Can I restrict who can see certain pages in Confluence?

Yes. Go to the page's restrictions and choose who can view or edit it. You can restrict by user, group, or role. Use this for sensitive information like security procedures or financial data, but keep most documentation open — the more people who can find and read it, the more useful it becomes.

What is the best way to handle documentation for a product that changes frequently?

Version your documentation. Create a parent page for each major version of your product, then add child pages under each version. Link to the current version prominently from your homepage. When you release a new version, create a new parent page and update the homepage link. This lets users find documentation for the version they are using without confusion.