To optimize for semantic search and RAG-based AI agents, you need to write and organize content in a way that aligns with how AI systems break down and retrieve information. Here are best practices specifically for maximizing AI retrievability:
Chunk Content into Manageable Sections
One question or task = one chunk of content.
Chunking refers to breaking text into discrete, meaningful units. In practice, this means keeping sections and paragraphs focused and of a moderate length. Each section under a heading should ideally answer one main question or subtopic. This granularity allows an AI to pull just the relevant chunk when responding to a query.
If chunks are too large (e.g., a single section rambles through multiple topics), the AI might include extraneous info or miss the specific answer. As mentioned, it’s fine to have a longer page as long as it’s well-organized, modern RAG systems can handle large documents, but smaller coherent sections give finer retrieval control https://support.atlassian.com/jira-service-management-cloud/docs/set-up-your-knowledge-base-to-improve-the-quality-of-ai-answers/ .
Consider a Cheat Sheet style or FAQ pages: it’s often best to format it as a question (heading) followed by a short answer (paragraph). That way, if the AI gets a question matching one of those, it can directly return the answer portion.
Explicitly Phrase Important Information
Semantic search relies on meaning, not just exact keywords. To aid it, write out important facts or answers in a straightforward way.
For example, if a common question is “What is the default password policy?”, ensure the documentation has a sentence like “The default password policy is X” (with X filled in) in a visible place. Don't bury critical facts in narrative form.
It can help to imagine the question a user would ask and make sure a direct answer appears in the text. This doesn’t mean turning your docs into a pure Q&A format (though a Q&A section can be helpful), but it does mean being mindful to state things directly.
If you’re describing a concept, include a line that succinctly defines it (so the AI can lift that definition). If you’re giving instructions, consider what the outcome or purpose is and state it clearly (e.g., “By completing these steps, you will have successfully installed the NetWorker Agent on the server”).
Use User’s Language and Synonyms
Include the words and phrases that users are likely to use when searching or asking questions.
People might phrase questions differently than the internal terminology. For instance, if your product has an official term “Access Card” but users often say “Key Card”, make sure to mention “key card” somewhere in the documentation (e.g., “Access Cards (often referred to as ‘key cards’) are used to secure the building...”).
Atlassian’s guidance gives a great example: an article titled “Request New Hardware” might also explicitly say “If you need a new laptop or keyboard, follow these steps...” so that terms like “laptop” and “keyboard” are presents https://support.atlassian.com/jira-service-management-cloud/docs/set-up-your-knowledge-base-to-improve-the-quality-of-ai-answers/ .
You can achieve this by sprinkling common alternative phrases in the text naturally or in a short “keywords” section. This practice greatly improves the chances of semantic search matching an everyday question to the right answer. It essentially bridges the gap between the user’s vocabulary and the documentation’s vocabulary.
Avoid Ambiguity and Be Specific
Ambiguity in content can confuse AI retrieval. Use specific identifiers when referencing things.
For example, instead of saying “If it fails, check the log,” specify what fails: “If the backup process fails, check the log.” By being explicit, you ensure that each sentence or paragraph has a clear meaning even out of context.
This ties back to avoiding excessive pronouns or references without antecedents. Additionally, avoid using the same name for different things.
If you have two unrelated systems both called “Gateway” internally, give them distinct identifiers in documentation (even if it’s “Gateway (AI Inference)” vs “Gateway (Network device)”) to prevent confusion.
An AI might not have the human intuition to separate two concepts with identical names unless you do so in text.
Structured Data and Formatting for AI
While we’ve covered using tables and lists for human readability in Best Practices for Writing Documentation for AEO - Structuring Pages and Content , consider how an AI might interpret structured data. Tables are generally fine (and AI can read them), but ensure table headers are clear and each cell’s meaning is evident.
If you list out properties or parameters, consider a definition list format (term –> definition) or a table with “Parameter / Description”.
This structured presentation can be easier for an AI to digest and for semantic search to pinpoint a definition of a specific term. Also, if you have multi-step processes that depend on sequence, number your steps clearly (semantic search might return a numbered list and preserving order is important).
In Confluence, each heading and list implicitly creates structure which many retrieval systems will use when indexing content.
Test with Queries
Although this is more of an iterative process tip, it’s worth mentioning: after writing content, think of sample questions someone might ask that should be answered by that content or use any variation with minimal words and context - yes, that happens.
Then try searching your Confluence (or if possible, ask your AI assistant if it’s available in a staging environment) with those questions. See if the right page/section comes up. If not, you may need to tweak wording or add a key phrase.
This kind of QA can greatly improve AEO, as you’re validating that the semantic signals in your text match the expected queries. For example, if you have a troubleshooting page titled “Cannot Connect to VSS VPN”, try searching Confluence for “VPN connection error” or “VPN not working”.
if your page doesn’t appear, consider adding those phrasings into the text (perhaps under a “Symptoms” subsection: “Symptoms: Users see a ‘VPN connection error’ message”). This way, both direct search and AI semantic search will have those terms to latch onto