Spruce up availability guidance

get-started/versioning-availability.md

@@ -16,32 +16,95 @@ Each number represents a specific level of change:
 
 It's important to understand this versioning system, for compatibility and [upgrade](/deploy-manage/upgrade.md) planning.
 
-## Availability of features
+## Understanding availability in the docs
 
-Elastic products and features have different availability states across deployment types:
+Elastic products and features have different availability states across deployment types and lifecycle stages. Our documentation uses badges to help you quickly identify where and when features are available for your specific environment.
 
-- **Generally Available**: Feature is production-ready (default if not specified)
-- **Beta**: Feature is nearing general availability but is not yet ready for production usage
-- **Technical preview**: Feature is in early development
-- **Coming**: Feature is announced for a future release
-- **Discontinued**: Feature is being phased out
-- **Unavailable**: Feature is not supported in this deployment type or version
+### What the badges mean
 
-Features may have different availability states between:
+Each badge provides up to three key pieces of information:
 
-- Elastic Stack versions (for example, 9.0, 9.1)
-- Serverless projects (Security, {{es}}, Observability)
-- Deployment types (and versions)
+- **Deployment type**: The environment where the feature is available (Stack, Serverless, ECE, ECK, etc.)
+- **Lifecycle state**: The development or support status of the feature (GA, Beta, etc.)
+- **Version**: The specific version the lifecycle state applies to
+
+#### Lifecycle states
+
+| State | Description |
+|-------|-------------|
+| **Generally Available (GA)** | Production-ready feature (default if not specified) |
+| **Beta** | Feature is nearing general availability but not yet production-ready |
+| **Technical preview** | Feature is in early development stage |
+| **Coming** | Feature announced for a future release |
+| **Discontinued** | Feature is being phased out |
+| **Unavailable** | Feature is not supported in this deployment type or version |
+
+### Badge context
+
+Badges can appear in two places:
+1. **Page headers**: Shows the overall availability across all deployment types
+2. **Section headers**: Indicates specific availability for content in that section
+
+### Where feature availability may differ
+
+Features may have different states between:
+
+- **[Elastic Stack](the-stack.md)** versions (e.g., 9.0, 9.1)
+- **Deployment types** (and deployment versions)
   - [Elastic Cloud Hosted](/deploy-manage/deploy/elastic-cloud/cloud-hosted.md)
   - [Elastic Cloud Serverless](/deploy-manage/deploy/elastic-cloud/serverless.md)
   - [Self-managed deployments](/deploy-manage/deploy/self-managed.md)
   - [Elastic Cloud Enterprise (ECE)](/deploy-manage/deploy/cloud-enterprise.md)
     - ECE deployment versions (for example, 4.0.0)
   - [Elastic Cloud on Kubernetes (ECK)](/deploy-manage/deploy/cloud-on-k8s.md)
     - ECK deployment versions (for example, 3.0.0)
+- **Serverless project types**
+  - Security
+  - Elasticsearch
+  - Observability
+
+### How to read the badges
+
+Here are some examples to help you understand how to read the availability badges.
+
+#### Example #1: Stack only feature
+
+```yaml {applies_to}
+stack: ga 9.1
+```
+- **Deployment type**: Elastic Stack
+- **Version**: 9.1
+- **Lifecycle**: Generally Available (GA) — default state
+
+#### Example #2: Serverless-only feature with project differences
+
+```yaml {applies_to}
+serverless:
+  security: beta
+  elasticsearch: ga
+```
+- **Deployment type**: Serverless 
+- **Lifecycle**: 
+  - Beta for Security projects
+  - Generally Available for Elasticsearch projects
+
+#### Example #3: Discontinued feature on one deployment type
+
+```yaml {applies_to}
+deployment:
+  ece: discontinued 9.2.0
+```
+- **Deployment type**: Elastic Cloud Enterprise
+- **Lifecycle**: Discontinued
+- **Version**: 9.2.0
+
+### Important tips when reading documentation
 
-When reading the Elastic documentation be sure to:
+- Always check feature lifecycle state for your specific deployment type and version
+- Pay attention to Elastic Stack version requirements
+- Note that Serverless features may vary by project type
+- Features without badges are generally available for all deployment types and versions
 
-- Check feature availability for your deployment type and version
-- Note stack version requirements
-- Be aware that Serverless features may vary by project type
+:::{tip}
+For contributors and those interested in the technical details, see the [Elastic docs syntax guide](https://elastic.github.io/docs-builder/syntax/applies/) for more information on how these badges are implemented.
+:::