[Internal]: Improvements to AI Assistant Documentation

[dhru42]

Description

What

Improve the Elastic Security AI Assistant documentation, with a strong focus on helping users extract value from AI features — especially around Knowledge Base (KB) creation and usage.

Why

Users are struggling to understand how to meaningfully use AI Assistant capabilities after upgrading to Elastic Cloud with enterprise licensing. Current documentation lacks:

• Clear working examples
• End-to-end guidance on KB setup and configuration
• Best practices for formatting and structuring KB content
• Context-specific explanations for how and when the assistant provides value

This gap is leading to frustration, trial-and-error learning, and delays in adoption — especially for customers with custom detection rules and content.

Key Improvements Needed

1. Working Examples for Common Use Cases

Add real, working examples that show the assistant in action. Examples should include:

• Investigating alerts
• Writing ES|QL queries
• Responding to security incidents
• Summarizing threat intelligence

2. Improve Knowledge Base documentation

Create a step-by-step guide on how to create a KB index for the AI Assistant, including:

• Required fields and mappings (e.g., semantic text, title, metadata)
• Example mappings and documents
• Index creation process in Kibana
• How to associate an index with the assistant
• How the description and query instruction fields affect performance

3. Formatting & Content Best Practices

Provide guidance on:

• How to structure documents for optimal RAG (retrieval-augmented generation) performance
• Suggested formats (e.g., key:value, markdown sections, narrative summaries)
• What works well vs. what to avoid
• Real-world KB examples for security teams (custom rules, asset inventories, etc.)

When

ASAP

Supporting Feedback

Real customer pain point documented from Elastic Cloud user:

"We cannot find any single working example on the documentation... We spent a lot of time just testing things while an example like this should be present on the documentation."

Resources

docs improvement

Which documentation set does this change impact?

Elastic On-Prem and Cloud (all)

Feature differences

improvement to current docs

What release is this request related to?

N/A

Serverless release

n/a

Collaboration model

The documentation team

Point of contact.

Main contact: @dhru42 @jamesspi

Stakeholders: @jamesspi

[benironside]

Closing this as complete since its only subissue has been completed. Per my discussion with Dhru, the other action items described in this issue have already been covered elsewhere. Will of course continue to improve AI docs in collaboration with Dhru and the GenAI team.