[Serverless]: Clarify "Beta" label meanings (add supportability description), and more clearly label "Technical Preview with clear supportability statements

[maggieghamry]

Description

Within the Serverless documentation:

• some pages clearly say preview at the top (which need to hover to see supportability statements), ie https://www.elastic.co/guide/en/serverless/current/security-add-exceptions.html
  

• some have the statement written out (ie https://www.elastic.co/docs/api/doc/serverless)
  

• some have Beta (with no hover or description) (ie https://www.elastic.co/docs/api/doc/serverless/operation/operation-findendpointlistitems)
  

It would be very helpful to add clear, consistent and formatted supportability statements for the supportability of Serverless APIs and Serverless products. Currently, the layout creates confusion about what can be supported for Serverless products and Beta does not appear to be explained in the Serverless documentation.

Resources

Platform - serverless team

Which documentation set does this change impact?

Elastic Cloud (Hosted and Serverless) only

Feature differences

This is specific to all Serverless documentation

What release is this request related to?

N/A

Collaboration model

The product team

Point of contact.

Main contact: @ppf2

Stakeholders:

[ppf2]

I see the following as our action plan to achieve clarity and consistency in documentation for preview and beta features:

1. Define the standard markdown text to use for all preview and beta features across the entire Elastic product line (Serverless and Stateful) and add the caveats about these features not intended for production use and the fact that these features are only supported at non-production severities (i.e. Sev 3).

Suggested text for preview features:

This feature is in technical preview (not recommended for production use) and may be changed or removed in a future release. Its functionality is supported only for Severity Level 3 cases and are not subject to the support SLA of official GA features.

Suggested text for beta features:

This feature is in beta (not recommended for production use). Its functionality is supported only for Severity Level 3 cases and are not subject to the support SLA of official GA features.

2. Once the suggested text is reviewed and approved by development leads, each dev team should update their documentation runbook to use the markdown [preview] and [beta] tags when documenting preview/beta features.

3. The docs team to ensure that all [preview] and [beta] markdowns are behaving the same when rendered on the UI across the documentation and API guides across all Elastic products.

@timto-elastic This looks like a wider scope than just Serverless and will need development alignment as well. Can the Docs team help start this discussion with the broader Development team on standardization? 😄 Thx!

cc: @calebchaney

[lcawl]

This work item is part of our versioning project where we'll add missing serverless- and cloud-specific admonitions in the current docs system and provide a longer-term strategy for the new docs system.

[maggieghamry]

Incidentally, I noticed the following in our Search

which links to a broken document for technical preview details:

https://www.elastic.co/guide/en/serverless/current/security-technical-preview-limitations.html

Interestingly, I tried googling and found 2 broken links are returned (top 2 results):