Structure content for AI

AI systems rely on structured, semantically meaningful content to correctly interpret and retrieve information. Structured content also improves discoverability on search engines and within internal tools.

Follow these best practices to structure your content:

• Use clear, descriptive headings. See Naming conventions for topics and sections.
• Break long paragraphs into unordered or ordered lists. See Best practices for writing with lists.
• Write in short, declarative sentences. See Use plain language.
• Use consistent formatting, such as tables, admonitions, text callouts, and code blocks, to signal meaning. See Including tables, Admonitions and text callouts, and Formatting reference.

The following table shows an example of the best way to structure content for optimized AI:

Do this	Don't do this
To configure an alert, follow these steps: Open Alert Settings. Select the condition type. Select Save.	Configuring alerts involves opening the settings, choosing a condition, and saving. Make sure you do this correctly, or alerts won't work.

Write clearly with plain language

Plain, direct language improves comprehension for both humans and machines. Ambiguous phrasing and product-centered language make it harder for AI to extract meaning or answers. AI performs better when content is direct, action-oriented, and structured around the user's needs. Clarity also supports readers with cognitive disabilities or translation tools, making your content more inclusive overall.

Follow these best practices for clear writing:

• Write in active voice and plain language. See Be active and present.
• Focus on what the user can do, not what the product does. See A word about Splunk docs.
• Keep sentences short and scoped to one idea.
• Avoid jargon and idioms. If you must use technical terms, define them clearly or link to a glossary like the Splexicon. See Use plain language.
• Avoid vague verbs like "understand", "know", or "handle". Use specific, measurable actions instead.
• Avoid vague pronouns like "this", "that", or "it" when the referent isn't clear. See Pronouns.
• Avoid using the subjunctive mood, such as would, should, and could, in factual or instructional content. See Write in indicative or imperative mood.
• Avoid anthropomorphisms like "Splunk thinks", "the system tries", or "the app wants". Use direct, factual language that states what the product returns. See Avoid anthropomorphisms.

The following table shows examples of clear, concise language:

Do this	Don't do this
Apply transformation rules to your data before it's indexed. For example, you can standardize field names, mask sensitive values, or filter out unwanted events.	Ingest Processor gives you the ability to easily handle your data however you need before it gets indexed.
You can route data to multiple destinations using configuration rules.	Ingest Processor allows you to easily route data however you need.

Support multimedia with metadata

AI can analyze images and videos, but only when they are supported by strong metadata. Optimizing nontext content ensures that it's accessible and usable in AI-powered systems, like image search or summarization tools. Follow these best practices for multimedia:

• Use descriptive file names, such as aws-ingest-screenshot.png.
• Add accurate, concise alt text for every image. See Using images with accessibility.
• Include transcripts and captions for videos and audio. See Best practices for including videos.
• Avoid including new information in an image that isn't covered in surrounding text. See Including images in Splunk docs.

The following table shows an example of an AI-optimized file name and alt text for a screenshot:

Do this	Don't do this
File name: aws-to-splunk-ingest.png Alt text: Screenshot showing AWS data being ingested into the Splunk platform.	File name: Image1 Alt text: image1.png

Prepare content for reuse and discovery

In addition to clear writing, AI systems need content that is consistently structured, tagged, and regularly maintained. When possible, use formats that machines can ingest and index easily.

Follow these best practices for AI content readiness:

• Add metadata where possible, such as author, last updated date, and topic tags, if metadata is supported by your authoring platform. If your authoring platform doesn't have built-in metadata options, you can still apply metadata manually using front matter in Markdown or tags in GitHub wikis.
• Use structured formats like HTML, Markdown, or JSON.
• Componentize content into reusable sections when possible, and use formatting patterns consistently, such as standard task steps and troubleshooting layouts.
• Link to related topics to increase findability. Don't leave topics isolated or duplicate effort across pages.
• Audit and update content on a regular basis.