Alerting GA - Alerts documentation

[mikecote]

Originally part of #81532, this issue encapsulates the missing documentation on alerts necessary for Alerting GA.

• API documentation API documentation for alerting and actions (asciidoc) #49705
• Alert types doc update Alert types doc update  #80632
• Ensure alerting docs point to the configuration page PR link [Alerting][Docs] Changed alerting documentation to point to a single source of explaining the configurations. #92942
• Cleanup README.md to remove duplication Cleanup alerting and actions README.md to remove duplication from docs #64198

[elasticmachine]

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

[mikecote]

I wonder if there are some APIs we should hold off formally documenting? This would open the opportunity to make breaking changes to them in a minor release 🤔 , For example, get_alert_instance_summary, get_alert_state, aggregate. They feel very tied to our underlying architecture and it could be a pain to support if we're changing how we deal with alerts as data.

[pmuellr]

I wonder if there are some APIs we should hold off formally documenting?

Yes, I feel that pain. But I'd bet we'll get issues about missing doc for those if we don't. Could we mark them as "experimental" or something?

[mikecote]

I'd bet we'll get issues about missing doc for those if we don't

I think that's fine, and we can reply that they are informal APIs. I've seen a few teams do so. For example, the dashboard export API, the saved objects relationships API, etc.

That way, if we have alerts as data, we can remove some summary APIs, it would be one thing less to maintain in the future as we can remove them and work with the internal teams that use them. If we document them as experimental, like most existing APIs, we still have some commitment to them to avoid breaking changes as much as possible.