reorg

Author: shainaraskas

docs/docset.yml

@@ -92,7 +92,10 @@ toc:
       - file: tabs.md
       - file: tagged_regions.md
       - file: titles.md
-  - file: versions-types.md
+  - folder: versions
+  - children:
+      - file: index.md
+      - file: version-components.md
   # nested TOCs are only allowed from docset.yml
   # to prevent them from being nested deeply arbitrarily
   - toc: development

docs/versions-types.md renamed to docs/versions/content-patterns.md

@@ -1,98 +1,7 @@
 ---
-navigation_title: "Versions and types"
+navigation_title: "Content patterns"
 ---
-# Documenting versions and deployment types
-
-In the new documentation system, we document features in a centralized place, regardless of the software version or deployment type it applies to. 
-For example, we might document the serverless and v9 implementations of a feature on a single page, and then use content patterns to highlight where prerequisites, options, or behaviors differ between these implementations.
-
-This approach improves our documentation in several ways: 
-
-* When a user arrives in our documentation from an outside source, they'll be likelier to land on a page or section that applies to them.
-* There is a single "source of truth" for each feature, which helps us to maintain consistency, accuracy, and maintainability of our documentation over time, and avoids "drift" between multiple similar sets of documentation.
-* Comparing and contrasting differences helps users to understand what is available to them, and improves awareness of the ways certain offerings might improve their experience.
-
-::::{note}
-This page documents the first version of our approach to documenting differences in versions and deployment types, using our current technologies. 
-Our approach might change as additional documentation features become available.
-::::
-
-## Basic concepts and principles
-
-:::{dropdown} Versioning facets
-There are multiple facets to versioning that we need to consider: 
-
-* **Elasticsearch / Kibana flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **Stack <version>**
-
-% TODO: Final term for "Stack"
-* **Deployment type:** The way Elastic is deployed. Either **Serverless** (sometimes "Elastic Stack Serverless"), **Elastic Cloud Hosted**, **Elastic Cloud on Kubernetes**, **Elastic Cloud Enterprise**, or **Self-managed**. 
-
-  All deployment types other than **Serverless** use the **Stack <version>** flavor of Elasticsearch / Kibana.
-
-% TODO: Final term for "Self-managed"
-
-* **Project type:** The Serverless project types where a feature can be used.
-
-* **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. 
-  
-  E.g. clients, Elastic Common Schema
-
-**How many facets do I need to use?**
-
-The role of these labels is providing a trust signal that the reader is viewing content that’s applicable to them. This means that the relevant labels should appear on all pages. However, we can choose to expose only one versioning plane on pages where only one plane is relevant:
-
-* Depending on what you're documenting, you might need to include information from multiple facets. For example, when relevant features exist at both the stack and the deployment level, both of these groups might be used together (e.g. security, user management, trust).
-
-* In some sections, such as **Explore and analyze**, features generally only differ by Elasticsearch flavor. In these cases, you can choose to include only this facet on the page.
-:::
-
-:::{dropdown} Defaults and hierarchy 
-
-You should not assume a default deployment type or Elasticsearch / Kibana flavor.
-
-Treat all flavors and deployment types equally. Don't treat one as the "base" and the other as the "exception".
-
-However, we should all display our flavors and versions in the same order for consistency. This order reflects organizational priorities.
-
-**Flavors:**
-
-1. Serverless
-2. Stack
-
-**Deployment types:**
-
-1. Serverless
-2. Elastic Cloud Hosted
-3. Elastic Cloud on Kubernetes
-4. Elastic Cloud Enterprise
-5. Self-managed
-
-When it comes to hierarchy of versions, always put the newest version first.
-:::
-
-:::{dropdown} Versions and lifecycle states
-
-In the V3 docs system, we currently document only our latest major versions (Stack 9.0+, ECE 4.0+, ECK 3.0+).
-
-Add version labels only when a feature was added as part of the major version release, or added in subsequent dot releases. Do not add version information to features added before these releases. For example, features added in 8.16 don't need an 8.16 label or a 9.0 label, but features added in 9.0 need a 9.0 label.
-
-From the latest major onward, the entire feature lifecycle should be represented. This means that you need to add separate labels for the following states:
-
-* beta or technical preview
-* GA
-* deprecated
-* removed
-
-We hope to simplify or consolidate these lifecycle labels in future.
-
-::::{warning}
-This feature doesn't currently work - currently, only one label will appear.
-::::
-
-:::
-
-
-## Content patterns
+# Version content patterns
 
 Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs.
 
@@ -109,7 +18,7 @@ Choose from:
 * [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections)
 * [Sibling pages](#sibling-pages)
 
-### Page-level `applies` tags
+## Page-level `applies` tags
 
 **Use case:** Provide signals that a page applies to the reader
 
@@ -121,7 +30,7 @@ Add tags for all **versioning facets** relevant to the page.
 
 See **Versions and lifecycle states** to learn when to specify versions in these tags.
 
-#### Example
+### Example
 [Manage your Cloud organization](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization.html)
 
 ### Section/heading-level `applies` tags
@@ -142,7 +51,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these
 **Example**
 See above
 
-### Inline `applies` tags
+## Inline `applies` tags
 
 ::::{warning}
 This feature doesn't currently work - we're working around it by using prose.
@@ -159,7 +68,7 @@ Currently, we don't have inline `applies` tags. Instead, append the information
 
 Because this approach is less clear, consider using words like `only` to help people to understand that this information indicates the applicability of a feature.
 
-#### Example
+### Example
 
 Spaces let you organize your content and users according to your needs.
 
@@ -189,7 +98,7 @@ Spaces let you organize your content and users according to your needs.
 ::::
 
 
-### Tabs
+## Tabs
 
 **Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process.
 
@@ -207,7 +116,7 @@ Try not to include information surrounding a procedure in the tabs. Make the tab
 
 Consider breaking up procedures into sets of procedures if only one section differs between contexts.
 
-#### Example
+### Example
 
 To create a space: 
 
@@ -252,21 +161,21 @@ To create a space:
 
 You can edit all of the space settings you just defined at any time, except for the URL identifier.
 
-### Sibling bullets 
+## Sibling bullets 
 
 **Use case:** Requirements, limits, other simple, mirrored facts.
 
 **Number to use:** Ideal is one per option (e.g. one per deployment type). You might consider nested bullets in limited cases.
 
-#### Examples
+### Examples
 
 ::::{tab-set}
 :group: one-two
 
 :::{tab-item} One
 :sync: one
 
-##### Required permissions
+#### Required permissions
 
 * **Serverless**: `Admin` or equivalent
 * **Stack v9**: `kibana_admin` or equivalent
@@ -275,7 +184,7 @@ You can edit all of the space settings you just defined at any time, except for
 :::{tab-item} Two
 :sync: two
 
-##### Create a space
+#### Create a space
 
 The maximum number of spaces that you can have differs by [what do we call this]: 
 
@@ -284,7 +193,7 @@ The maximum number of spaces that you can have differs by [what do we call this]
 :::
 ::::
 
-### Prose (inline)
+## Prose (inline)
 
 **Use case:** Clarifying or secondary information
 
@@ -294,22 +203,22 @@ The maximum number of spaces that you can have differs by [what do we call this]
 
 Sometimes, you can just preface a paragraph with version info. 
 
-#### Example
+### Example
 
 If you're managing a Stack v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. 
 
 When a role is assigned to *All Spaces*, you can’t remove its access from the space settings. You must instead edit the role to give it more granular access to individual spaces.
 
 
-### Callouts
+## Callouts
 
 **Use case:** Happy differences, clarifications
 
 Some sections don’t apply to, say, Serverless, because we manage the headache for you. Help people to feel like they’re not getting shortchanged with a callout.
 
 If there’s a terminology change or other minor change (especially where x equates with y), consider handling as a note for simplicity.
 
-#### Examples
+### Examples
 
 * *In **Manage TLS certificates** section*:
 
@@ -322,7 +231,7 @@ If there’s a terminology change or other minor change (especially where x equa
   :::{note}
   In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**.
 
-### Prose (explanatory paragraphs and sections)
+## Prose (explanatory paragraphs and sections)
 
 **Use case**: Differences with a "why"
 
@@ -332,7 +241,7 @@ Sometimes, a close explanation of the differences between things helps people to
 
 You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough.
 
-#### Example
+### Example
 
 ::::{tab-set}
 :group: one-two
@@ -370,7 +279,7 @@ You can augment Elastic Cloud security features in the following ways:
 
 You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough.
 
-### Sibling pages
+## Sibling pages
 
 **Use case:**
 
@@ -387,20 +296,10 @@ When version differences are just too large to be handled with any of our other
 
 % Down the line, if we need to, we could easily convert version-sensitive sibling pages into “picker” pages
 
-#### Example
+### Example
 
 [Cloud Hosted deployment billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/cloud-hosted-deployment-billing-dimensions.html)
 
 and its sibling
 
-[Serverless project billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions.html)
-
-## Best practices
-
-### Screenshots
-
-Follow these principles to use screenshots in our unversioned documentation system:
-
-* Reduce screenshots when they don’t explicitly add value.
-* When adding a screenshot, determine the minimum viable screenshot and whether it can apply to all relevant versions.
-* Take and maintain screenshots for only the most recent version, with very few exceptions that should be considered on a case-by-case basis.
+[Serverless project billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions.html)