Organize your content with a clear structure so both readers and AI can navigate it. Key structuring practices include:
Use Clear Page Titles and Section Headings
Each page should cover a focused topic and have a descriptive title that reflects its content (for example, “How to Set Up SSO Authentication” rather than “Setup Guide”).
Within pages, use a logical hierarchy of headings (H1, H2, H3) to break the content into sections. Descriptive headings make it easy to scan and help an AI locate specific information. Remember that AI reads headings just like regular text, using them to convey key points is encouraged
Leverage Lists, Tables, and Formatting
Structure information using bullet points, numbered steps, and tables where appropriate.
Lists are excellent for procedures or key takeaways, and tables can organize reference data neatly. Breaking up text with such elements improves readability.
For example, a step-by-step how-to guide should use a numbered list for each step, and a policy page might use a table to summarize settings or roles. This formatting not only aids human readers but also helps AI parse the content into logical pieces.
One Topic per Page (or Clearly Separated Sections)
Avoid mixing different types of information or widely different audiences in the same document.
Each page should ideally serve a single purpose or user group. For instance, end-user how-to instructions should be separate from developer API reference or internal policy notes.
If a page grows long with multiple subtopics, consider splitting it into multiple pages or at least dividing it into well-marked sections. Confluence allows content hierarchy, so you might have a parent page like “VPN Setup” with child pages “VPN on Windows” and “VPN on Mac” or a single page with Windows and Mac as H2 sections.
The rule of thumb is that each section or page should cover a distinct topic of value. Atlassian recommends having distinct articles for distinct topics (e.g. separate articles for VPN on Mac vs. Android), or if combined in one article, using clear headings for each topic.
This modular structure ensures an AI can pinpoint exactly the section relevant to a query.
Maintain a Logical Page Hierarchy
Organize pages within Spaces in a logical tree so that related pages are grouped.
For example, group all “Troubleshooting” pages under a parent troubleshooting guide, or all “User Guides” in one section of the space. A clear hierarchy provides context, an AI might infer context from a page’s neighbours or parents, and it certainly helps human users browse the content. Avoid dumping pages in one flat list with no structure.
Be Careful with Confluence Macros and Nested Content
Confluence offers macros like info panels, expand/collapse sections, etc. Use these features to enhance readability (for example, an expandable section for an optional advanced detail), but be cautious about how they affect retrievability. Ensure that important information is not hidden in a way that search or an AI might skip. Notably, avoid placing critical text inside expand panels or info panels that are nested within tables, because some AI indexing engines may not read panel content inside tables.
As a best practice, use panels and expands for supplemental content rather than primary content, and test your Confluence search to see that such content is indexed.
Always provide alt text for images and diagrams so that if an AI can’t interpret an image, the alt text or accompanying caption describes it.