Best Practices for Writing Documentation for AEO - Use of Context, Definitions, and Examples
Rich context and explanatory content make your documentation more self-contained and intelligible, especially when an AI might deliver only a fragment of it as an answer. Pay attention to providing background, definitions, and examples:
Provide Context in Introductions
Start pages or major sections with a brief introduction that outlines what the content is about and why it’s important.
This sets the stage for readers who might not know the background and also helps AI frame the information.
For example, a page titled “ITS Private Cloud Guidelines” might begin with a sentence like, “The ITS Private Cloud guidelines are pivotal for ensuring secure, efficient, and reliable use of infrastructure resources. Adhering to these standards helps maintain the integrity and performance of the ITS Private Cloud.”
Such an intro gives the who/what/why. If an AI pulls an excerpt about a specific rule from this page, that contextual sentence might also be included in the answer, making it clearer. Similarly, in a how-to guide, a short overview of what the user will achieve by following the steps can be very useful.
Define Terms and Acronyms
Don’t assume all readers know the internal jargon or technical terms.
When you introduce a term that’s unique or not common knowledge, briefly define it. You can do this inline (e.g., “Our system uses a Cache Server, a temporary storage area that saves frequently used data for quick access.”) or have a dedicated glossary page for many terms.
Definitions ensure that if an AI is asked “What does X mean?” it can find the answer in your documentation. Even within procedural answers, an AI might include a bit of definition if it helps clarify the answer.
Confluence doesn’t have a native glossary feature out of the box, but you can create one manually or with an add-on; at minimum, consider a FAQ or “Terminology” page that an AI could draw upon for conceptual questions. As mentioned earlier, FAQs or Cheat Sheets in general are a great tool to help AI and users find meaningful information from your documentation.
Avoid using undefined abbreviations.
For instance, say “Service Level Agreement (SLA)” rather than just “SLA” until you’ve defined it. This way, the documentation is accessible to newcomers and to AI models that might not have your organization’s acronyms in their training data.
Include Examples to Illustrate Key Points
Whenever applicable, provide examples.
They turn abstract instructions into concrete understanding. For an end user guide, this might be screenshots or a sample scenario (“e.g., an example of a completed form”).
For developer or admin documentation, it could be code snippets, command-line examples, or configuration file samples. Clearly marked examples (perhaps using an Example: prefix or a styled panel) help users learn, and an AI may use them to answer questions like “What does a sample X look like?”.
For instance, if the question is “What is the format of the vss-cli config file?”, having that sample block in your page means the AI can potentially quote it.
Examples also help disambiguate instructions. if you show the expected outcome, there's less room for confusion.
Ensure your examples are realistic and correctly formatted (if showing code or CLI output, use the Confluence code block macro for clarity).
Use Cases and Scenarios
Augment procedural guides with brief use-case descriptions.
Explaining when or whysomeone would perform a procedure provides valuable context. For instance, before listing steps to configure a feature, you might note: “Use this procedure when you need to guide a user installing the ITS Private Cloud VPN.”
Such context means an AI can better match a user’s real-life question (“I have a user, how do I give steps to install the ITS Private Cloud VPN ?”) with the documentation answer. It bridges the gap between theoretical documentation and practical application.
Also, troubleshooting articles should mention the symptoms and scenarios they address (e.g., “If you cannot log in to the ITS Private Cloud X and see error XYZ, follow these steps…”). This way, an AI can pick up on the symptom description and link it to the solution steps in that article.
Avoid Assumed Context Across Pages
Each page should be as self-contained as reasonably possible.
Minimize phrases like “as discussed earlier” or “see above” without proper reference. If information is crucial, either briefly restate it or explicitly link to it.
An AI might surface a section of a page alone, and if that section relies on prior context that wasn’t included, the answer could be confusing. By ensuring sections include any context they need (or at least a link to it), you improve the standalone clarity of each chunk of content.