How to write for AI search (AEO)
AI optimized content is structured and presented in a way that makes it easy for both humans and AI-powered search tools to read, understand, and cite your content.
Scannable content helps users and AI grasp what's important
Not only are scannable content types—nested H1/H2 headings with descriptive content labels, lists, table data, and FAQs—ideal for optimizing your content for AI search, they are also crucial to helping human readers cope with information overload and time constraints. Users prefer scanning content rather than reading paragraphs of text. Scannable content helps users in three main ways:
- It saves time: Users don't need to read through large blocks of text to find the details they need.
- It reduces cognitive load: Users can consume scannable content without expending extra mental energy.
- It's accessible: Scannable content addresses many (but not all) accessibility principles.
Top tips for creating AI-optimized content
Follow these guidelines to create scannable, AI-search optimized content.
Understand your audience's needs and expectations
Be useful and add value. Create an information architecture and content hierarchy that aligns with your audience's needs and expectations. User research and feedback can help you understand the purpose of what you're writing and what your audience is looking for.
See examples
Match your article titles and content to what your target audience is actually trying to accomplish, not to a product feature name or category.
| Audience | What they need | Do this | Instead of this |
|---|---|---|---|
| Site Reliability Engineers | Fix a failing service quickly | Troubleshoot high response time in microservices | Overview of PurePath distributed tracing |
| Security Analysts | Identify runtime vulnerabilities immediately | How to filter vulnerable third-party libraries | The lifecycle of a CVE |
| Capacity Planners | Report on historical resource consumption | Generate host CPU reports using DQL | Dashboards |
Put key information in the first paragraph
Write like a journalist. Place definitions, summaries, and takeaways up front so users can quickly understand the purpose of your content and decide whether they want to read further. Include only one idea per paragraph.
See examples
Each example below opens with a descriptive, FAQ-style heading followed by a first paragraph that immediately defines the feature or capability.
Example 1: Define a core product feature
What is Smartscape?
Smartscape is a real-time dependency graph that continuously maps all components in your application environment, from the data center and hosts down to specific services and processes. Dynatrace Intelligence uses this real-time topology map to identify the exact root cause of performance anomalies.
Example 2: Introduce a new capability
How Dynatrace Application Security protects against runtime vulnerabilities
Dynatrace Application Security automatically detects and blocks vulnerabilities in your runtime environments. It leverages your existing OneAgent deployment to identify vulnerable third-party libraries and zero-day attacks without requiring additional code changes or scanners.
Example 3: Summarize an integration
What's included in the Dynatrace integration for ServiceNow?
The Dynatrace integration for ServiceNow automatically creates and updates incident tickets based on Dynatrace problem notifications. This syncs real-time observability data directly into your IT service management workflows.
Front-load sentences with keywords and search terms
Consider what search terms users are likely to search for and incorporate those keywords into your content, ideally near the beginning of sentences. This helps users and AI agents quickly find what they're looking for. For example, if users are searching for the phrase "Query Grail," you might write, "To query Grail, use the following syntax."
See examples
In each example, the key search term is moved to the beginning of the sentence so users and AI agents can immediately identify the topic.
Example 1
Before: To filter your log records by status, use the filter command in DQL.
After: The DQL filter command allows you to isolate log records by specific status codes or attributes.
Example 2
Before: You can pull metrics from your AWS environment using the Amazon CloudWatch integration.
After: The Amazon CloudWatch integration pulls infrastructure metrics directly from your AWS environment into Dynatrace.
Example 3
Before: When you want to group requests into a single logical endpoint, you can set up key requests.
After: Key requests group specific, business-critical service requests so you can monitor them with dedicated anomaly detection thresholds.
Use simple, recognizable words
Write for a global audience in plain, conversational American English. While technical language is both expected and necessary in the software industry, use industry-standard customer-facing terminology and avoid internal jargon to make the experience as smooth as possible.
See examples
Replace internal jargon and overly technical language with plain, industry-standard terms your audience will immediately recognize.
Example 1
Before: Deploy the binary footprint to commence telemetry ingestion.
After: Install OneAgent to begin collecting metrics.
Example 2
Before: Interrogate the data lakehouse for strings.
After: Query Grail for specific log messages.
Example 3
Before: Harness the AI causation engine to unearth the genesis of the outage.
After: Use Dynatrace Intelligence to determine the root cause of the outage.
Use parallel writing structures
In lists and headings, use consistent sentence structure where possible to make content elements easier to compare. For example, use only action-verb phrases or noun phrases in your headings and lists, not a mix of both.
See examples
Action verbs for how-to steps
To deploy OneAgent on Linux:
- Download the installer.
- Verify the signature.
- Run the installation script.
Noun phrases for a reference list
OneAgent-monitored hosts offer the following metrics:
- CPU consumption
- Memory usage
- Network latency
- Disk I/O
Consistent verb-phrase titles for tutorial sections
- Configure the Kubernetes API integration
- Deploy the Dynatrace Operator
- Verify the connection status
Structure your content using descriptive H2/H3 headings
Use headings to structure content into sections and subsections. Clear and concise headings and subheadings make content easier to scan and organize hierarchically.
Use conversational FAQ-style question-answer structures in your headings where appropriate, for example, "What is Smartacape?" This helps users and AI agents quickly understand the content's purpose and find the information they need.
Avoid "ing" gerund verb forms in headings and subheadings (for example, "creating" and "configuring") because they are passive. For stronger statements, use active verb forms instead (for example, "create" and "configure").
See examples
Action verb headings
- H1: Manage user access in Dynatrace
- H2: Create a management zone
- H2: Assign permissions to a user group
- H3: Validate access rules
FAQ-style headings
- H1: Metric behavior and anomalies
- H2: What is a dimensional metric?
- H2: How does Dynatrace Intelligence calculate baselines?
- H2: Why is my host showing as offline?
Descriptive troubleshooting headings
- H1: Troubleshooting guide
- H2: Troubleshoot common platform issues
- H3: Resolve missing distributed traces
- H2: Troubleshoot OneAgent installation errors
- H3: Fix ActiveGate connection timeouts
- H2: Troubleshoot common platform issues
Use numbered and bulleted lists
Lists help users scan complex information. Use numbered lists when the sequence of list items is important, for example, when documenting a procedure; otherwise, use bulleted lists. Keep lists as short as possible. Use the correct indentation to convey the hierarchy of list items.
See examples
Numbered list for a how-to procedure
Follow these steps to generate a DQL API token:
- Go to Access tokens.
- Select Generate new token.
- Enter a token name.
- Select the Read logs scope.
- Select Generate.
Bulleted list for supported technologies
Dynatrace natively supports the following database technologies:
- Oracle
- Microsoft SQL Server
- PostgreSQL
- MongoDB
Bulleted list for prerequisites
Before migrating to Grail, ensure that:
- Your tenant is updated to version 1.250 or later.
- You have administrator privileges.
- Log Monitoring v2 is turned on.
Use bold text for emphasis
Use bold text to call out UI elements such as button labels and page names. Bold text can also be used sparingly to draw attention to featured phrases or terminology. Don't use quotation marks, italics, font color, or underlining to emphasize text.
See examples
Navigate a web UI
To view your host health, go to Infrastructure > Hosts and select your target server.
Interact with buttons
Enter your query in the text box and select Run query.
Reference page names
The Deployment status page displays the current version of all installed OneAgents across your cluster.
Structure data using tables
Use tables to present data that is best understood in a grid format, for example, when comparing features or listing specifications. Rather than writing a "wall of text" to explain the relationships, differences, and similarities between multiple list items, use tables to present the information in a clear and concise way that conveys the relationships and promotes scannability.
Verify correct table data display across all supported screen dimensions, including dynamic resizing and text wrapping in web browsers.
See examples
Use tables when you need to compare multiple items across consistent dimensions.
Metric comparisons
| Metric | OneAgent | ActiveGate | Synthetic monitor |
|---|---|---|---|
| Host CPU | Yes | No | No |
| Service response time | Yes | Yes | Yes |
| Availability | No | No | Yes |
Permission mappings
| Role | View dashboards | Edit settings | Manage users |
|---|---|---|---|
| Viewer | Yes | No | No |
| Operator | Yes | Yes | No |
| Administrator | Yes | Yes | Yes |
Support matrix
| Feature | Windows | Linux | macOS |
|---|---|---|---|
| OneAgent | Yes | Yes | No |
| ActiveGate | Yes | Yes | No |
| Browser extension | Yes | Yes | Yes |
Break up big paragraphs and don't mix content types
Consider if you're writing conceptual explanatory content, a step-by-step procedure, or reference material. Each of these content types is best presented in a different format. Don't mix content types within the same section or paragraph. For example, don't write a step-by-step procedure in paragraph form; use a numbered list instead. Don't write a reference list in paragraph form; use a table instead. Use short paragraphs and sentences that relate to the specific content type you're writing about. Also, extra white space makes your content easier to scan.
See examples
Example 1: Break up a dense paragraph into a list
Before: Dynatrace provides many features for web applications, including the ability to track every user click, which is called Real User Monitoring or RUM, and you can also send simulated traffic from different geographies using browser monitors to see if your site is down. Session Replay also lets you watch video-like recordings of user errors.
After: Dynatrace Digital Experience Monitoring (DEM) provides three core capabilities for web applications:
- Real User Monitoring (RUM): Tracks actual user interactions and performance metrics.
- Synthetic monitoring: Simulates traffic from global locations to proactively detect outages.
- Session Replay: Provides video-like recordings of user sessions for troubleshooting.
Example 2: Move prerequisites out of inline prose
Before: Before you begin installing OneAgent, you need to make sure you have root privileges on your Linux machine, and you should also ensure that your firewall allows outbound HTTPS connections to your tenant URL.
After: Prerequisites:
- Root or sudo privileges on the target machine.
- Outbound HTTPS access (port 443) from the host to your Dynatrace tenant URL.
Example 3: Separate an explanation from a how-to procedure
Before: A request naming rule allows you to clean up dynamically generated URLs so that Dynatrace Intelligence can accurately baseline the endpoint. To set one up, go to Settings > Service monitoring and select Request naming rules.
After: A request naming rule allows you to clean up dynamically generated URLs so that Dynatrace Intelligence can accurately baseline the endpoint.
To create a request naming rule:
- Go to Settings > Service monitoring.
- Select Request naming rules.
Example 4: Separate an explanation from reference data
Before: By default, Dynatrace alerts you when disk space drops below a critical threshold, specifically warning at 10% and critical at 5%.
After: By default, Dynatrace alerts you when disk space drops below a critical threshold.
Default disk alerting thresholds:
- Warning: 10% free space remaining.
- Critical: 5% free space remaining.
Use definitive, authoritative language, like an analyst
Avoid dry, neutral descriptions and extreme opinions. AI agents prefer definitive, authoritative language that makes it clear that your content is a reliable source of information. Avoid hedging language such as "might," "could," "may," and "possibly" unless there is genuine uncertainty about the information you're providing. This helps both users and AI agents understand that your content is trustworthy and can be cited with confidence.
See examples
Replace hedging language with direct, confident statements that affirm what your product does.
Example 1
Before: Dynatrace Intelligence might find the root cause by looking at your traces.
After: Dynatrace Intelligence determines the precise root cause by analyzing all distributed traces in real time.
Example 2
Before: Installing OneAgent could possibly result in a small overhead.
After: OneAgent operates with negligible overhead, typically consuming less than 1% of CPU capacity.
Example 3
Before: Application Security may help you stop vulnerabilities.
After: Application Security blocks attacks at runtime and identifies vulnerable libraries in your production environment.
Cite trusted experts and sources
AI engines favor content with strong expertise, authority, and trustworthiness signals. To strengthen your content's credibility:
- Include quotations from internal or external subject-matter experts with verified credentials.
- Write detailed author bios that outline the author's expertise and experience.
- Use case studies, personal stories, and original images to demonstrate first-hand experience.
- Cite reputable external sources to support your claims.
Avoid in-page ads and other interruptions
AI agents can be interrupted or blocked by ads, pop-ups dialogs, tabs, JavaScript widgets, and other dynamic content. Avoid these interruptions to ensure that your content is fully accessible to AI agents and can be cited effectively.
See examples
Place architecture diagrams directly in the page body
Instead of a button labeled Log in to view the ActiveGate deployment architecture, place the architecture explanation and any accompanying static images directly in the documentation body.
Embed code snippets directly in Markdown
Instead of hosting an essential DQL script inside an embedded third-party interactive widget that requires JavaScript to render, paste the script directly into a standard Markdown code block on the page.
Avoid "click to reveal" patterns for important content
Instead of placing troubleshooting steps for a Crash Loop BackOff behind a dynamic Click to reveal solution button, print the solution directly in plain HTML text on the page.
Make sure all key information is visible on the page
AI agents can only read text that is displayed in HTML on the page. If key information is hidden within expandable elements, images, links to related content in other articles, or non-HTML formats, AI agents might not be able to access and cite your content. Ensure that all links are functional and lead to relevant content that supports the information you're providing.
See examples
Example 1: Surface information hidden behind interactive controls
Before: A button labeled "Show unsupported operating systems" that requires user interaction to display the list.
After: Display the information directly on the page. For example: The following legacy operating systems are not supported in OneAgent v1.280: Windows Server 2008, CentOS 6.
Example 2: Surface definitions hidden in tooltips
Before: The term "management zone" is defined only in a tooltip that appears on mouse-over.
After: Include the definition directly in the article body, for example as a FAQ-style H2 section:
What is a management zone?
Management zones are a powerful information-partitioning mechanism that promotes focus on specific parts of your observed topology and the sharing of relevant team-specific data while simultaneously ensuring access control.
Example 3: Surface reference data hidden in downloadable files
Before: A link to download a ZIP file containing JSON payload examples for the Metrics API.
After: Provide JSON payload examples directly in the documentation as copyable code blocks so that AI agents and users can read and use them immediately without needing to follow a link or download a file.