Improve UX for finding documentation for each alert type

[mikecote]

The documentation for alert types states that For domain-specific alert types, refer to the documentation for that app. but users are still having a hard time finding the documentation related to the alert type presented in the management creation UI.

There may be a few causes for this:

• The alert type doesn't have documentation
• There's no centralized place / catalogue in the documentation listing these alert types
• The UI doesn't point to the docs on how to configure the selected alert type

and others.

[elasticmachine]

Pinging @elastic/kibana-alerting-services (Team:Alerting Services)

[mikecote]

cc @gchaps, in case you have alternate proposals

[gchaps]

@mikecote It would be nice to get the information to the user as close as possible to the point of use. Can we include a link in the UI that opens a flyout with the information?

[mikecote]

@mikecote It would be nice to get the information to the user as close as possible to the point of use. Can we include a link in the UI that opens a flyout with the information?

@gchaps That would be a good idea. Would the expectation be to open a tab to the documentation website or to copy a snippet of that documentation in a flyout right within Kibana?

[gchaps]

My preference would be to include a snippet of the documentation in the flyout on the right.

[pmuellr]

To require alert types to provide documentation, we can add a required link template string property as part of the alert type, so you couldn't register an alert without doc. Perhaps that would be good for actions as well.

[mikecote]

@mikecote to consider #80953 while doing analysis.

[mikecote]

A couple of notes from an offline discussion I had with @gchaps, @mdefazio and @bmcconaghy:

• See if alerting documentation can be merged (this and this) - Alerting GA/7.10 documentation #81532
• Link to external pages from the alerting docs (ex: "see uptime alerts") - Alerting GA/7.10 documentation #81532
• Core UI team to do some user testing - User / UX testing for creating alerts #82001
• Come up with a documentation template to guide developers writing alert type documentation - Documentation template for alert and action types #82000
• Add a "read the docs" item in the alert management page - Add a link to documentation in the alerts and actions management UI #81909
• Come up with a short description for each alert type - Add descriptions to alert types #81850
• Make alert flyout link to alert docs and have a short description - Add description and documentation link in alert flyout #81526
• Go over some designs for create flows that could integrate more help and / or documentation [Owner @mdefazio]

---

* question mark (?) next to owner means it wasn't decided who yet so TBD
* Any item that touches the UI will wait until @mdefazio has a proposal.