---
title: "Optimize Docs for AI"
canonical: "https://documentation.chaos.com/space/DOCSGUIDE/113289629/Optimize%20Docs%20for%20AI"
format: markdown
---
This article provides tips for optimizing the documentation for AI tools.
## **How does AI analyze the information?**
---
- In separate chunks, not as a continuous narrative.
- Does not respect relationships between separate chunks.
- Does not read macros.
- Does not read visuals and complex tables.
Understanding how AI handles the information in Confluence helps you understand why you need to follow the tips in the next sections.
## **Information for AI must be:**
---
- Explicit *(The more explicit and less ambiguous the information is, the better the retrieval accuracy is.)*
- Clear
- Well-structured
- User-focused
- Self-contained (not context-dependent)
- Contextually complete
- Optimized
- Focused contexts
- Having a clear relationship between concepts
- Lacking contextual dependencies
- Providing text alternatives/equivalents for visual content
- Chunks must be independent of other chunks *(The more a chunk can stand alone while maintaining clear relationships to related content, the better it can be understood by the AI.)*
- Having consistent terminology
- Ensuring semantic clarity
- Having a simple structure
- Having a clear hierarchy
## **Information for AI must avoid:**
---
- Context-dependent information
- Assuming users know
- A large or overly broad context
- Ambiguity
- Separating critical information from chunks
- Complex structure
- Depending mainly on visuals and tables
- Layout-dependent information
- PDF forms
The following sections explain these tips in greater detail.
### **Information Structure**
---
This section explains how the documentation content must be structured:
- Select the structure wisely - avoid using too many macros. Choose a simplified, clear, predictable structure because AI does not read macros.
- Simplify the page structure by reducing or eliminating custom UI elements, JavaScript-driven dynamic content, and complex animations.
- Use simple interactive elements and not complex JavaScript.
- Keep layouts simple
- Divide the documents into smaller, semantically coherent chunks - for example, use many sections inside a page that have explicit headings rather than one very long page without any subsections; or divide the pages into subpages with explicit titles.
- Design your content hierarchy so that each section carries sufficient context to be understood independently, while maintaining clear relationships to parent and sibling content. The hierarchical position of each document or section is very important.
- Ensure each section includes enough context to be understood independently:
Product family: Which product or service area
Product name: Specific product or feature name
Version information: When applicable
Component specificity: Subfeatures or modules
Functional context: What the user is trying to accomplish
- Sections should ideally make sense when encountered in isolation.
- Ensuring sections remain actionable when encountered independently.
- Consider starting each section with brief context about its scope and prerequisites, using descriptive headings that indicate what the section accomplishes, and including essential background information without assuming prior reading. Look for sections that reference "as mentioned above," "now that you've," or "with everything configured" as signals that context needs to be made explicit.
- Do not separate critical information from its context, do not make individual chunks ambiguous or incomplete.
**Example**
**Bad:**
Au*thentication tokens expire after 24 hours by default.*
*The system provides several configuration options for different environments.*
*When implementing the login flow, ensure you handle this appropriately*.
**Good: **
*Authentication tokens expire after 24 hours by default. When implementing the login flow, ensure you handle token expiration by refreshing tokens before the 24-hour limit or implementing proper error handling for expired token Responses.*
*The system provides several configuration options for different environments, including custom token expiration periods.*
- Avoid large and overly broad contexts. Keep it straight to the point.
- Do not assume the user knows previous steps, give explicit instructions:
**Example:**
**Bad:**
*## Setting up webhooks*
*Configure your endpoint URL in the dashboard and test the connection.*
**Good:**
*## Setting up CloudSync webhooks*
*Before configuring webhooks, ensure you have:*
*- A publicly accessible HTTPS endpoint*
*- Valid SSL certificate*
*- CloudSync API credentials*
- Configure your endpoint URL in the CloudSync dashboard under Settings > Integrations, then use the "Test connection" button to verify setup.
- Don’t embed critical information into images, videos, and diagrams.
- Information should not be layout–dependent, i.e. to rely on tables, positioning, images, etc.
- Poorly structured tables should be converted into lists.
- Add alternative text to all pictures, diagrams, etc. AI does not understand visuals and rely on text.
- Establish consistent terminology for your product's unique concepts and use them systematically. The important thing is that for any given chunk, there’s a clear and consistent signal that connects it to your product or feature.
### **Terminology**
---
This section gives tips for terminology usage in the documentation:
- Establish consistent terminology for your product's unique concepts and use them systematically. Include specific product or feature names when documenting functionality. This doesn't mean you should repeat the product name in every sentence or heading. The important thing is that for any given chunk, there’s a clear and consistent signal that connects it to your product or feature.
**Example:** *Vantage Product Activation instead of Product Activation*
### **Visuals**
---
This section gives tips for handling visuals in the documentation:
- Add alternative text to all pictures, diagrams, etc. AI does not understand visuals and relies on text.
- Do not embed critical information in images, diagrams, and videos. Instead, represent them as numbered step lists and keep the visuals as supplements.
###
**Tables**
---
This section gives tips for handling tables in the documentation:
- Do not make the information dependent on visual layouts, positioning, or table structures.
- Complex or poorly structured comparison tables with merged headers must be converted into structured lists. - this is not applicable to our documentation.
- Supplement or replace complex tables where relationships between cells convey important meaning.
- Keep simple reference tables where each row is self-contained.
**Example:**
###
**Troubleshooting Articles**
---
This section gives tips for handling troubleshooting articles that explain how specific error messages are handled:
- When documenting troubleshooting steps, quote the exact error messages and describe observable symptoms alongside solutions.
## **General Example**
---
**Bad Example - assumes the user knows info, dependent on previous sections:**
*## Updating webhook URLs*
*Now change the endpoint to your new URL and save the configuration.*
Documentation sections that depend on readers following a linear path or remembering details from previous sections become problematic when processed as independent chunks.
**Good Example - self-explanatory, context-independent, clear instructions:**
*## Updating webhook URLs*
*To update webhook endpoints in CloudSync:*
*1. Navigate to Settings > Webhooks in your CloudSync dashboard.*
*2. Select the webhook you want to modify.*
*3. Change the endpoint URL to your new address, and click Save.*
The self-contained version works when retrieved as an isolated chunk because it includes the essential context. Ex: what system (CloudSync), where to find the setting (Settings > Webhooks), and complete steps