[Alerting Docs] Questions and updates for observability alerting docs

[jasonrhodes]

@vinaychandrasekhar had some comments and questions about the state of our current Observability Rules and Alerting docs. I'm attempting to capture most of what he was asking about here so we can discuss with docs team and then chart a course for solving/improving. Vinay, please correct anything I've misrepresented here, and add anything else I've missed.

• Who creates/manages our "Elasticstack" terraform provider docs?
  • There are a few scattered mentions of rules and alerting in these docs, are we sure these are organized in a way that users understand and can navigate?
    • Guides > Managing Kibana rule and connector resources
    • Kibana > Resources > elasticstack_kibana_alerting_rule
    • Others?
  • How can we include more comprehensive examples in Terraform for each rule? (“Export to API/Terraform” idea and cost?)
• Elastic alerting docs
  • Users may arrive at this "REST APIs" page and be confused why there is no alerting section here (it's because alerting APIs are not part of Elasticsearch, but will end users understand this or be frustrated by the need for this institutional knowledge?)
  • This Kibana alerting docs page only explicitly mentions "stack rules" with a category below them mentioning "Observability rules" which links to another page. The page that actually lists the observability rules is 2 clicks away. Do our users understand how to navigate this?

[jasonrhodes]

Note: the terraform provider is maintained in the elastic/terraform-provider-elasticstack repo, along with its docs. (H/T @smith)

[dedemorton]

I'll answer what I can and tag folks for other stuff:

Who creates/manages our "Elasticstack" terraform provider docs?

I have no idea who maintains these docs, so I won't try to comment on the detailed questions. @bmorelli25 Do you know who maintains our terraform provider docs? Do we have any control over these docs?

Users may arrive at this "REST APIs" page and be confused why there is no alerting section here (it's because alerting APIs are not part of Elasticsearch, but will end users understand this or be frustrated by the need for this institutional knowledge?)

I think this problem will be solved by the API site that we are setting up. @lcawl might have some thoughts to add here.

This Kibana alerting docs page only explicitly mentions "stack rules" with a category below them mentioning "Observability rules" which links to another page. The page that actually lists the observability rules is 2 clicks away. Do our users understand how to navigate this?

This is a real problem that we need to solve. Historically we've kept the alerting rules for observability in the Observability Guide to make sure that Observability users can find the info (navigating our current siloed system is a nightmare). When we migrate our content to docsmobile (our new docs tooling), we will have a unified navigation for the first time ever and be able to group things quite differently. For now, I am planning to make some iterative improvements to the Observability alerting docs to make all the valid rules available in one place (I've started tracking my list of improvements in #3622). @lcawl may have more to add because she owns the Kibana alerting docs. I plan to work pretty closely with her to come up with a better user experience with our alerting docs since I just own the Observability-related rules.

[jasonrhodes]

@dedemorton / @bmorelli25 for clarity, I was able to find who maintains the terraform provider docs here: #3669 (comment)

[jasonrhodes]

This will also be useful information for us if we want to contribute to those terraform docs: https://developer.hashicorp.com/terraform/registry/providers/docs

[lcawl]

For interest's sake, I've made updates to the Terraform docs in the past per https://github.com/elastic/platform-docs-team/issues/81, elastic/terraform-provider-elasticstack#387. I believe at the time I was told that by default they're deriving strings where possible from our openAPI specifications, which is cool if that's still true. There seems to be some disparity between what's supported in the APIs and what's supported in Terraform (e.g. around the notify_when parameter when I was working on it), so it's not necessarily an immediate 1:1 mapping to what's available in the APIs.