Holistic documentation for out of the box (OOTB) assets for Integrations

[daniela-elastic]

Background

As Elastic begins to offer a more comprehensive out of the box (OOTB) experience for integrations, we want to make documentation a first class citizen, part and parcel of the product. Today we have OOTB dashboards and we are imminently launching OOTB alert templates with near-term plans to also provide OOTB SLO rules and ML jobs. In the medium term we are also to expand the OOTB assets to other content that will make the integrations smarter when used together with AI. For example, additional content will be knowledge bases that help LLMs answer user questions when assessing the health and performance of a service, or when troubleshooting an operational issue. Similarly, we might add MCP tools such that they can enable the LLMs to further assist users.

Today our documentation does not put a lot of emphasis on the OOTB experience and the information is sparse and sprinkled in various places. For example, we have just a short paragraph on the new capability for out-of-the-box alert rule templates which is easy to miss. We should lead with OOTB and this should be front and center of the capabilities that Elastic offers, highlighting how easy it is to get started.

Holistic strategic solution - Suggested doc structure

• High level intro to everything that comes out of the box today. It doesn’t require YOU to do the work. We’ve done the work for YOU, so you can start using all the OOTB (pre-built stuff) right away! We need to sell this. Suggest we take it out of the Manage Elastic Agent integrations section (which sounds more like work that the customer has to do, invest money and time in)
  • Can we have an OOTB section that talks about everything that the customer is getting pre-made (ready to use). What you need to do to get the asset (eg you can’t get the asset unless you install the integration)
• Introduction to OOTB alert templates and how to use them (can this be improved?)
• FAQ -
  • how do we help customers understand the difference between OOTB OOTB alert rules and alert templates for integrations (which are essentially OOTB alert templates)
  • Be clear and concise about typical customer questions. An FAQ format is better than long text

MVP and tactical solution - individual integration pages

In the individual doc page for the individual integration (observability NGINX integration example)

1. Recommended alerts and alert rule template.
   • Can we show the recommended alerts and alert rule config in the documentation page for each integration so that the customer doesn’t have to log in to kibana, set up the service and configure/install the integration, JUST SO they can see the recommended alerts. Can we offer something like this?
2. Rule query
   • Can we link to github or some other place where we store the ESQL query for the rule? And in the doc page which just described with natural language what that rule is about (and if the user wants to see the rule, they go to the github which contains the code.
   • Alternatively, can we autogen the rule in the doc? Something like this
3. Why - why are we recommending this alert?
   • For each alert - Can we provide a reason why we are recommending it?
4. Guidelines on context-based thresholds and other config
   • For each alert - can we provide notes on some things to take into account with the config - eg, in many cases thresholds are contextual and while we may want to provide a number, we also need to explain to the user how to adjust the number based on their particular use case.

[florent-leborgne]

Thanks @daniela-elastic for the detailed issue

@colleenmcginnis @alaudazzi I think the requested content is a mix of:

1. Checking how to extract/generate reference pieces from the code for individual integrations
   • List all "assets" that come out of the box with an integration
   • Hopefully descriptions about all of these as well
2. A deeper update of the overall narrative around integrations. Just by looking, it's obvious that there are too many pages under https://www.elastic.co/docs/reference/fleet/manage-integrations and no clear narrative/user path. I'd take as an example the work done here Edit and restructure time series docs #3461 (about a totally different topic)

#\1 is obviously more important for exhaustiveness and accuracy but with the way we're distributed and integration docs are built, nothing prevents from looking into both workstreams at the same time.
Lmk what you think, we should sync and chat about how to plan these.

@daniela-elastic, since this looks like a pretty big piece of work with some strategic dimension to it, do you have some input on whether this issue (or part of it) is specifically tied to a product release? This will help us to get a better sense of where to put this in our current list of priorities. Thanks!

[daniela-elastic]

Hi @florent-leborgne thank you the quick analysis on how we could approach this. You are exactly right - ideally we should provide the holistic approach. And also, nothing is stopping us from working on the individual integration doc pages in parallel with the holistic approach.

In terms of when we need the documentation, ideally we were targeting the launch of OOTB Alert rule templates user experience which is currently blocked due to a bug (original target release was 9.2.0 but now the earliest possible is 9.2.1)

[florent-leborgne]

@daniela-elastic thanks for the quick answer. Given the current date of 9.2.1 (Nov 11th - might be sooner), I don't think we can deliver all of this on time for the release.
What do you think would be something minimal we could publish for that version while we carry out the bigger work?

[daniela-elastic]

I think if we start working on a page that mentions all the OOTB assets we have (dashboards, alert templates and soon others), perhaps that would be a good beginning. Thoughts?

Separately, for the moment we don't have a good automatic solution to generate the alert rule template content in order to add it to the individual integration documentation pages. In the meantime we could attempt to manually add all that info to the README file but obviously this should be a temporary solution because it introduces a mounting tech (doc) debt. cc @lalit-satapathy @tommyers-elastic

[florent-leborgne]

@colleenmcginnis @alaudazzi thoughts on this?

I think we could create sub-issues here to split the tasks:

I think if we start working on a page that mentions all the OOTB assets we have (dashboards, alert templates and soon others), perhaps that would be a good beginning. Thoughts?

1. have some improvements around the Manage integrations page delivered with a refined narrative and more clarity between what comes OOTB with integrations versus what users need to do themselves. I think that the various bits of content already exist, it might rather be a question of better structuring the content to highlight and clarify these parts.

In the meantime we could attempt to manually add all that info to the README file but obviously this should be a temporary solution because it introduces a mounting tech (doc) debt.

2. I'm not clear on the work and effort that this represents. This sounds huge to do manually unless there's a limited number of integrations that require this? Would that be carried out by the engineering team and reviewed by writers? Or can you clarify the expectations and collaboration model you have in mind there @daniela-elastic? This may be something we could leverage AI for?

3. Another task to investigate how to generate this?

[alaudazzi]

@daniela-elastic @florent-leborgne

Separately, for the moment we don't have a good automatic solution to generate the alert rule template content in order to add it to the individual integration documentation pages.

We might actually have a solution to automate the doc updates on each integration README.
@mjwolf and I are testing the LLM Integration Documentation Generation tool, which basically generates/updates the integration documentation using an LLM (specifically Gemini).

[daniela-elastic]

I had a discussion with @alaudazzi regarding the following:
We are launching alert rule templates for integrations imminently. This capability already exists and we will be launching the actual templates for a number of integrations (and more to come). You can see a list of the integrations and upcoming plans here.

We really need some documentation help with a centralized doc page for the alert rule templates that the individual integration pages can point to. A page that explains to users what these templates are and how to use them. @tommyers-elastic has created the automation where the individual integration doc page picks up the alert rules and points to this centralized doc page. What we need is:

• A doc writer to review the new section in the individual integration doc pages, related to alert rules - there's some common text plus some of the content for each alert rule template
• A doc writer to update the centralized doc page with explanation of what the alert rule templates are and how to use them.
  @bmorelli25 are you able to help us with this please

[alaudazzi]

@daniela-elastic

• A doc writer to review the new section in the individual integration doc pages, related to alert rules - there's some common text plus some of the content for each alert rule template
• A doc writer to update the centralized doc page with explanation of what the alert rule templates are and how to use them.

I can help you here. What's the timeline?

[lalit-satapathy]

I had a discussion with @alaudazzi regarding the following:

Thanks @daniela-elastic!!

@tommyers-elastic has created the automation where the individual integration doc page picks up the alert rules and points to this centralized doc page.

Its a template within elastic-package, as per PR here, yet to be merged.

The template generates content like this: