From f25efff9ffcf0a002de797c125ef21b36d274765 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 7 Feb 2025 16:40:53 -0500 Subject: [PATCH 01/55] version docs --- docs/docset.yml | 1 + docs/versions-types.md | 169 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 docs/versions-types.md diff --git a/docs/docset.yml b/docs/docset.yml index a7963cd2..02d18d65 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -92,6 +92,7 @@ toc: - file: tabs.md - file: tagged_regions.md - file: titles.md + - file: versions-types.md # nested TOCs are only allowed from docset.yml # to prevent them from being nested deeply arbitrarily - toc: development diff --git a/docs/versions-types.md b/docs/versions-types.md new file mode 100644 index 00000000..f2aee6e2 --- /dev/null +++ b/docs/versions-types.md @@ -0,0 +1,169 @@ +--- +navigation_title: "Versions and types" +--- +# 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 arrive on a page 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 flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **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 ** Elasticsearch flavor. + +% TODO: Final term for "Self-managed" +* **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 you’re viewing content that’s applicable to you. 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 features are added both at 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 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 represents 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 release, or added in subsequent dot releases. Do not add version information to features added before these releases (e.g. features added in 8.16 don't need an 8.16 label or 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 + +Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. + +### Page-level `applies` tags + +**Use case:** Provide signals that a page applies to the reader + +**Number to use:** Minimum to add clarity + +**Approach:** + +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** +TODO + +### Section/heading-level `applies` tags + +**Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed + +**Number to use:** Minimum to add clarity + +**When to use:** When the section-level scope differs from the page-level scope + +**Example** +TODO + +### Inline `applies` tags + +**Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version + +**Number to use:** Three max. If the number of tags is longer than that, consider breaking up the list by facet. + +### Tabs + +**Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. + +**Number to use:** Max 4 or 5 + +Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose: + +* “In version x and earlier, Spaces were referred to as Places.” +* “In version x and earlier, click the Permissions tab”. + +Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. + +Consider breaking up procedures into sets of procedures if only one section differs between contexts. + +### 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 + +##### Required permissions + +* **Serverless**: `Admin` or equivalent +* **Stack v9**: `kibana_admin` or equivalent + +##### Create a space + +The maximum number of spaces that you can have differs by [what do we call this]: + +* **Serverless**: Maximum of 100 spaces. +* **Stack v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. + +##### Prose (inline) + +**Use case:** Clarifying or secondary information + +Sometimes, you can just preface a paragraph with version info. Do this in cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews. + +### Screenshots + +* 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 +* Screenshots should always only represent the most recent version, with very few exceptions that should be considered on a case-by-case basis. From 6c7de9352b649e1dd0e40cf75709cf4409235166 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:23:51 -0500 Subject: [PATCH 02/55] more --- docs/versions-types.md | 280 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 257 insertions(+), 23 deletions(-) diff --git a/docs/versions-types.md b/docs/versions-types.md index f2aee6e2..cb93d6b3 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -8,7 +8,7 @@ For example, we might document the serverless and v9 implementations of a featur This approach improves our documentation in several ways: -* When a user arrives in our documentation from an outside source, they'll be likelier to arrive on a page that applies to them. +* 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. @@ -22,30 +22,34 @@ Our approach might change as additional documentation features become available. :::{dropdown} Versioning facets There are multiple facets to versioning that we need to consider: -* **Elasticsearch flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **Stack ** +* **Elasticsearch / Kibana flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **Stack ** + +% 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 ** Elasticsearch flavor. + All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. % TODO: Final term for "Self-managed" -* **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. E.G. clients, Elastic Common Schema +* **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 you’re viewing content that’s applicable to you. 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: +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 features are added both at the stack and the deployment level, both of these groups might be used together (e.g. security, user management, trust). +* 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 flavor. +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 represents organizational priorities. +However, we should all display our flavors and versions in the same order for consistency. This order reflects organizational priorities. **Flavors:** @@ -67,7 +71,7 @@ When it comes to hierarchy of versions, always put the newest version first. 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 release, or added in subsequent dot releases. Do not add version information to features added before these releases (e.g. features added in 8.16 don't need an 8.16 label or a 9.0 label). +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: @@ -89,11 +93,24 @@ This feature doesn't currently work - currently, only one label will appear. Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. +Choose from: +% this should become a quick-ref table + +* [Page-level `applies` tags](#page-level-applies-tags) +* [Section/heading-level `applies` tags](#sectionheading-level-applies-tags) +* [Inline `applies` tags](#inline-applies-tags) (currently just prose) +* [Tabs](#tabs) +* [Sibling bullets](#sibling-bullets) +* [Prose (inline)](#prose-inline) +* [Callouts](#callouts) +* [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections) +* [Sibling pages](#sibling-pages) + ### Page-level `applies` tags **Use case:** Provide signals that a page applies to the reader -**Number to use:** Minimum to add clarity +**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). **Approach:** @@ -101,25 +118,73 @@ 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** -TODO +#### 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 +:::{applies} +:ece: all +:hosted: all +:eck: all +:stack: all +::: + **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed -**Number to use:** Minimum to add clarity +**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). **When to use:** When the section-level scope differs from the page-level scope **Example** -TODO +See above ### Inline `applies` tags +::::{warning} +This feature doesn't currently work - we're working around it by using prose. +:::: + **Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version -**Number to use:** Three max. If the number of tags is longer than that, consider breaking up the list by facet. +**Number to use:** Three max. If the number of tags is longer than that, consider: + +* Breaking up the list by facet +* Using labels that don't have version / lifecycle information and deferring that information to the page or section for the feature + +Currently, we don't have inline `applies` tags. Instead, append the information to the bullet item in bolded square brackets `**[]**`. Add all information within a single set of square brackets. The brackets should appear after any final punctuation. + +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 + +Spaces let you organize your content and users according to your needs. + +::::{tab-set} +:group: one-two + +:::{tab-item} One +:sync: one + +* Each space has its own saved objects. +* Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. +* Each space has its own navigation. **[Stack v9 only]** + +::: +:::{tab-item} Two +:sync: two + + +* Learn about internal users, which are responsible for the operations that take place inside an Elasticsearch cluster +* Learn about service accounts, which are used for integration with external services that connect to Elasticsearch +* Learn about the services used for token-based authentication +* Learn about the services used by orchestrators **[Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes]** +* Learn about user lookup technologies +* Manage the user cache + +::: +:::: + ### Tabs @@ -127,15 +192,63 @@ TODO **Number to use:** Max 4 or 5 -Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose: +Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: -* “In version x and earlier, Spaces were referred to as Places.” -* “In version x and earlier, click the Permissions tab”. +* In version 9.1 and earlier, **Spaces** were referred to as **Places**. +* + ::::{note} + In version 9.1 and earlier, click the **Permissions** tab. + :::: Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. Consider breaking up procedures into sets of procedures if only one section differs between contexts. +#### Example + +To create a space: + +:::::{tab-set} +:group: stack-serverless + +::::{tab-item} Serverless +:sync: serverless + +1. Click **Create space** or select the space you want to edit. +2. Provide: + + * A meaningful name and description for the space. + * A URL identifier. The URL identifier is a short text string that becomes part of the Kibana URL. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier later. + +3. Customize the avatar of the space to your liking. +4. Save the space. +:::: + +::::{tab-item} Stack v9 +:sync: stack + +1. Select **Create space** and provide a name, description, and URL identifier. + The URL identifier is a short text string that becomes part of the Kibana URL when you are inside that space. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier once you create the space. + +2. Select a **Solution view**. This setting controls the navigation that all users of the space will get: + * **Search**: A light navigation menu focused on analytics and Search use cases. Features specific to Observability and Security are hidden. + * **Observability**: A light navigation menu focused on analytics and Observability use cases. Features specific to Search and Security are hidden. + * **Security**: A light navigation menu focused on analytics and Security use cases. Features specific to Observability and Search are hidden. + * **Classic**: All features from all solutions are visible by default using the classic, multilayered navigation menus. You can customize which features are visible individually. + +3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. + + :::{note} + Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure [Kibana Security](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). + ::: +4. Customize the avatar of the space to your liking. +5. Save your new space by selecting **Create space**. +:::: + +::::: + +You can edit all of the space settings you just defined at any time, except for the URL identifier. + ### Sibling bullets **Use case:** Requirements, limits, other simple, mirrored facts. @@ -144,26 +257,147 @@ Consider breaking up procedures into sets of procedures if only one section diff #### Examples +::::{tab-set} +:group: one-two + +:::{tab-item} One +:sync: one + ##### Required permissions * **Serverless**: `Admin` or equivalent * **Stack v9**: `kibana_admin` or equivalent +::: +:::{tab-item} Two +:sync: two + ##### Create a space The maximum number of spaces that you can have differs by [what do we call this]: * **Serverless**: Maximum of 100 spaces. * **Stack v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. +::: +:::: -##### Prose (inline) +### Prose (inline) **Use case:** Clarifying or secondary information -Sometimes, you can just preface a paragraph with version info. Do this in cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews. +**Number to use:** ~ once per section (use your judgement) + +**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews + +Sometimes, you can just preface a paragraph with version info. + +#### 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 + +**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 + +* *In **Manage TLS certificates** section*: + + :::{tip} + Elastic Cloud manages TLS certificates for you. + ::: + +* *In a **Spaces** overview* + + :::{note} + In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**. + +### Prose (explanatory paragraphs and sections) + +**Use case**: Differences with a "why" + +**When to use:** Comparative overviews + +Sometimes, a close explanation of the differences between things helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. + +You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. + +#### Example + +::::{tab-set} +:group: one-two + +:::{tab-item} One +:sync: one + +The way that TLS certificates are managed depends on your deployment type: + +In **self-managed Elasticsearch**, you manage both of these certificates yourself. + +In **Elastic Cloud on Kubernetes**, you can manage certificates for the HTTP layer. Certificates for the transport layer are managed by ECK and can’t be changed. However, you can set your own certificate authority, customize certificate contents, and provide your own certificate generation tools using transport settings. + +In **Elastic Cloud Enterprise**, you can use one or more proxy certificates to secure the HTTP layer. These certificates are managed at the ECE installation level. Transport-level encryption is managed by ECE and certificates can’t be changed. +::: + +:::{tab-item} Two +:sync: two + +**Managed security in Elastic Cloud** + +Elastic Cloud has built-in security. For example, HTTPS communications between Elastic Cloud and the internet, as well as inter-node communications, are secured automatically, and cluster data is encrypted at rest. + +You can augment Elastic Cloud security features in the following ways: + +* Configure traffic filtering to prevent unauthorized access to your deployments. +* Encrypt your deployment with a customer-managed encryption key. +* Secure your settings with the Elasticsearch keystore. +* Allow or deny Cloud IP ranges using Elastic Cloud static IPs. + +[Learn more about security measures in Elastic Cloud](https://www.elastic.co/cloud/security). + +::: +:::: + +You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. + +### Sibling pages + +**Use case:** + +* Processes that have significant differences **across multiple procedures** +* Chained procedures where not all of the procedures are needed for all contexts / where the flow across procedures is muddied when versioning context is added +* Very complex pages that are already heavily using tabs and other tools we use for versioning differences, making it hard to add another “layer” of content +* Beta to GA transitions? Hide the beta doc and leave it linked to the GA doc, which will presumably be more stable? + +**Number to use:** As few as possible. Consider leveraging other ways of communicating versioning differences to reduce the number of sibling pages. + +**When to use:** + +When version differences are just too large to be handled with any of our other tools. Try to avoid creating sibling pages when you can. + +% Down the line, if we need to, we could easily convert version-sensitive sibling pages into “picker” pages + +#### 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 -* 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 -* Screenshots should always only represent the most recent version, with very few exceptions that should be considered on a case-by-case basis. +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. From fbb667e524263ca0e706eac3294fa28d2582fb96 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:27:13 -0500 Subject: [PATCH 03/55] add project type --- docs/versions-types.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/versions-types.md b/docs/versions-types.md index cb93d6b3..2fed1e50 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -29,6 +29,8 @@ There are multiple facets to versioning that we need to consider: All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. +* **Project type:** The Serverless project types where a feature can be used. + % TODO: Final term for "Self-managed" * **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. From 1b640f8fd18a07257245c9ead9ec7f16498dff45 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:28:52 -0500 Subject: [PATCH 04/55] move note --- docs/versions-types.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/versions-types.md b/docs/versions-types.md index 2fed1e50..1a011c31 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -29,9 +29,10 @@ There are multiple facets to versioning that we need to consider: All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. +% TODO: Final term for "Self-managed" + * **Project type:** The Serverless project types where a feature can be used. -% TODO: Final term for "Self-managed" * **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. E.g. clients, Elastic Common Schema From 87f36b6a151f3439551276f17cf4e15a04ad8595 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:31:15 -0500 Subject: [PATCH 05/55] remove broken link --- docs/versions-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions-types.md b/docs/versions-types.md index 1a011c31..a9c7e8c2 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -242,7 +242,7 @@ To create a space: 3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. :::{note} - Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure [Kibana Security](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). + Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure Kibana Security. ::: 4. Customize the avatar of the space to your liking. 5. Save your new space by selecting **Create space**. From d6e76d6a993a766201c4731929e72a5a77969066 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:43:25 -0500 Subject: [PATCH 06/55] reorg --- docs/docset.yml | 5 +- .../content-patterns.md} | 143 +++--------------- docs/versions/index.md | 120 +++++++++++++++ 3 files changed, 145 insertions(+), 123 deletions(-) rename docs/{versions-types.md => versions/content-patterns.md} (68%) create mode 100644 docs/versions/index.md diff --git a/docs/docset.yml b/docs/docset.yml index 02d18d65..f2094577 100644 --- a/docs/docset.yml +++ b/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 diff --git a/docs/versions-types.md b/docs/versions/content-patterns.md similarity index 68% rename from docs/versions-types.md rename to docs/versions/content-patterns.md index a9c7e8c2..32e39fc0 100644 --- a/docs/versions-types.md +++ b/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 ** - -% 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 ** 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,13 +161,13 @@ 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 @@ -266,7 +175,7 @@ You can edit all of the space settings you just defined at any time, except for :::{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,14 +203,14 @@ 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 @@ -309,7 +218,7 @@ Some sections don’t apply to, say, Serverless, because we manage the headache 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) \ No newline at end of file diff --git a/docs/versions/index.md b/docs/versions/index.md new file mode 100644 index 00000000..b82540f2 --- /dev/null +++ b/docs/versions/index.md @@ -0,0 +1,120 @@ +--- +navigation_title: "Versions and types" +--- +# 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 + +### 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 ** + +% TODO: Final term for "Stack" +* **Deployment type:** The way Elastic is deployed: + * **Serverless** (sometimes "Elastic Stack Serverless") + * **Elastic Cloud Hosted** + * **Elastic Cloud on Kubernetes** + * **Elastic Cloud Enterprise** + * **Self-managed** + + All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. + +% TODO: Final term for "Self-managed" + +* **Project type:** The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability**. + +* **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. + +### 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. + +### 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 + +Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. + +Choose from: +% this should become a quick-ref table + +* [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) +* [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) +* [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) +* [Tabs](/versions/content-patterns.md#tabs) +* [Sibling bullets](/versions/content-patterns.md#sibling-bullets) +* [Prose (inline)](/versions/content-patterns.md#prose-inline) +* [Callouts](/versions/content-patterns.md#callouts) +* [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) +* [Sibling pages](/versions/content-patterns.md#sibling-pages) + +## 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. From 55c90f54d119c02d72b53cd981a785970c7c9c0b Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:47:20 -0500 Subject: [PATCH 07/55] hello --- docs/versions/content-patterns.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 32e39fc0..0252bb52 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -1,5 +1,11 @@ --- navigation_title: "Content patterns" +applies: + stack: all + serverless: all + hosted: all + eck: all + ece: all --- # Version content patterns @@ -20,6 +26,8 @@ Choose from: ## Page-level `applies` tags +*see [`applies`](/syntax/applies.md)* + **Use case:** Provide signals that a page applies to the reader **Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). @@ -41,6 +49,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these :stack: all ::: +*see [`applies`](/syntax/applies.md#section)* **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed @@ -226,7 +235,7 @@ If there’s a terminology change or other minor change (especially where x equa Elastic Cloud manages TLS certificates for you. ::: -* *In a **Spaces** overview* +* *In a **Spaces** overview*: :::{note} In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**. From f4081e9ac53ebebfb3db0c72262114744aaf0c4e Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:49:15 -0500 Subject: [PATCH 08/55] fixie linkie --- docs/versions/content-patterns.md | 4 ++-- docs/versions/index.md | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 0252bb52..720e15b6 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -30,7 +30,7 @@ Choose from: **Use case:** Provide signals that a page applies to the reader -**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). **Approach:** @@ -53,7 +53,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed -**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). **When to use:** When the section-level scope differs from the page-level scope diff --git a/docs/versions/index.md b/docs/versions/index.md index b82540f2..3957056e 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -19,6 +19,10 @@ Our approach might change as additional documentation features become available. ## Basic concepts and principles +* [Versioning facets](#versioning-facets) +* [Defaults and hierarchy](#defaults-and-hierarchy) +* [Versions and lifecycle states](#versions-and-lifecycle-states) + ### Versioning facets There are multiple facets to versioning that we need to consider: From dd0c5f1f7141fd4499749ced5e2c32aaf01ceba6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:51:22 -0500 Subject: [PATCH 09/55] fixie another linkie" --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 720e15b6..da1038d5 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -49,7 +49,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these :stack: all ::: -*see [`applies`](/syntax/applies.md#section)* +*see [`applies`](/syntax/applies.md#sections)* **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed From 353997d02a41c1a656da7b50c04d7c3f59160f41 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:52:27 -0500 Subject: [PATCH 10/55] it's my first day, ok? --- docs/docset.yml | 2 +- docs/versions/content-patterns.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docset.yml b/docs/docset.yml index f2094577..57fbf6fb 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -95,7 +95,7 @@ toc: - folder: versions - children: - file: index.md - - file: version-components.md + - file: content-patterns.md # nested TOCs are only allowed from docset.yml # to prevent them from being nested deeply arbitrarily - toc: development diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index da1038d5..3db2a4dd 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -30,7 +30,7 @@ Choose from: **Use case:** Provide signals that a page applies to the reader -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). **Approach:** @@ -53,7 +53,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). **When to use:** When the section-level scope differs from the page-level scope From 63ecd4c7060ceecc9e3d6e5faea31b2659010ce1 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:59:32 -0500 Subject: [PATCH 11/55] try this --- docs/docset.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docset.yml b/docs/docset.yml index 57fbf6fb..4db50d20 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -93,7 +93,7 @@ toc: - file: tagged_regions.md - file: titles.md - folder: versions - - children: + children: - file: index.md - file: content-patterns.md # nested TOCs are only allowed from docset.yml From 9faf68530f793d5ad5ca88bbbb63345d98789c8a Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:19:50 -0500 Subject: [PATCH 12/55] add elastic.dev to external hosts --- docs/docset.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docset.yml b/docs/docset.yml index 4db50d20..cb3a28c6 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -20,6 +20,7 @@ external_hosts: - commonmark.org - github.io - github.com + - elastic.dev exclude: - '_*.md' subs: From d98bbaba7223c75f77dcd4be93a87987f660ad0a Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:27:26 -0500 Subject: [PATCH 13/55] cloud, not stack --- docs/versions/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 3957056e..d3044b2a 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -26,11 +26,11 @@ Our approach might change as additional documentation features become available. ### 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 ** +* **Elasticsearch / Kibana flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **Stack ** % TODO: Final term for "Stack" * **Deployment type:** The way Elastic is deployed: - * **Serverless** (sometimes "Elastic Stack Serverless") + * **Serverless** (sometimes "Elastic Cloud Serverless") * **Elastic Cloud Hosted** * **Elastic Cloud on Kubernetes** * **Elastic Cloud Enterprise** From 320ec37e3ae86e7ee8c94f8953ea064ace2ef1a0 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:29:59 -0500 Subject: [PATCH 14/55] fix weird order --- docs/versions/content-patterns.md | 35 +++++++++++++++---------------- docs/versions/index.md | 2 +- 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 3db2a4dd..4bfe1890 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -19,8 +19,8 @@ Choose from: * [Inline `applies` tags](#inline-applies-tags) (currently just prose) * [Tabs](#tabs) * [Sibling bullets](#sibling-bullets) -* [Prose (inline)](#prose-inline) * [Callouts](#callouts) +* [Prose (inline)](#prose-inline) * [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections) * [Sibling pages](#sibling-pages) @@ -202,23 +202,6 @@ The maximum number of spaces that you can have differs by [what do we call this] ::: :::: -## Prose (inline) - -**Use case:** Clarifying or secondary information - -**Number to use:** ~ once per section (use your judgement) - -**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews - -Sometimes, you can just preface a paragraph with version info. - -### 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 **Use case:** Happy differences, clarifications @@ -240,6 +223,22 @@ 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 (inline) + +**Use case:** Clarifying or secondary information + +**Number to use:** ~ once per section (use your judgement) + +**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews + +Sometimes, you can just preface a paragraph with version info. + +### 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. + ## Prose (explanatory paragraphs and sections) **Use case**: Differences with a "why" diff --git a/docs/versions/index.md b/docs/versions/index.md index d3044b2a..30ef0da4 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -108,8 +108,8 @@ Choose from: * [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) * [Tabs](/versions/content-patterns.md#tabs) * [Sibling bullets](/versions/content-patterns.md#sibling-bullets) -* [Prose (inline)](/versions/content-patterns.md#prose-inline) * [Callouts](/versions/content-patterns.md#callouts) +* [Prose (inline)](/versions/content-patterns.md#prose-inline) * [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) * [Sibling pages](/versions/content-patterns.md#sibling-pages) From 70db05b57d06e19e5286b0f893e2541152340611 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:32:01 -0500 Subject: [PATCH 15/55] more --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 4bfe1890..cb625f45 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -111,7 +111,7 @@ Spaces let you organize your content and users according to your needs. **Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. -**Number to use:** Max 4 or 5 +**Number to use:** Max 4 or 5 (in a deployment type / versioning context - might be different for other situations) Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: From 2666675ddd65313d30c62426a71241fca0fdf4b4 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Fri, 7 Feb 2025 16:40:53 -0500 Subject: [PATCH 16/55] version docs --- docs/docset.yml | 1 + docs/versions-types.md | 169 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 170 insertions(+) create mode 100644 docs/versions-types.md diff --git a/docs/docset.yml b/docs/docset.yml index a7963cd2..02d18d65 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -92,6 +92,7 @@ toc: - file: tabs.md - file: tagged_regions.md - file: titles.md + - file: versions-types.md # nested TOCs are only allowed from docset.yml # to prevent them from being nested deeply arbitrarily - toc: development diff --git a/docs/versions-types.md b/docs/versions-types.md new file mode 100644 index 00000000..f2aee6e2 --- /dev/null +++ b/docs/versions-types.md @@ -0,0 +1,169 @@ +--- +navigation_title: "Versions and types" +--- +# 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 arrive on a page 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 flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **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 ** Elasticsearch flavor. + +% TODO: Final term for "Self-managed" +* **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 you’re viewing content that’s applicable to you. 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 features are added both at 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 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 represents 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 release, or added in subsequent dot releases. Do not add version information to features added before these releases (e.g. features added in 8.16 don't need an 8.16 label or 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 + +Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. + +### Page-level `applies` tags + +**Use case:** Provide signals that a page applies to the reader + +**Number to use:** Minimum to add clarity + +**Approach:** + +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** +TODO + +### Section/heading-level `applies` tags + +**Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed + +**Number to use:** Minimum to add clarity + +**When to use:** When the section-level scope differs from the page-level scope + +**Example** +TODO + +### Inline `applies` tags + +**Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version + +**Number to use:** Three max. If the number of tags is longer than that, consider breaking up the list by facet. + +### Tabs + +**Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. + +**Number to use:** Max 4 or 5 + +Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose: + +* “In version x and earlier, Spaces were referred to as Places.” +* “In version x and earlier, click the Permissions tab”. + +Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. + +Consider breaking up procedures into sets of procedures if only one section differs between contexts. + +### 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 + +##### Required permissions + +* **Serverless**: `Admin` or equivalent +* **Stack v9**: `kibana_admin` or equivalent + +##### Create a space + +The maximum number of spaces that you can have differs by [what do we call this]: + +* **Serverless**: Maximum of 100 spaces. +* **Stack v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. + +##### Prose (inline) + +**Use case:** Clarifying or secondary information + +Sometimes, you can just preface a paragraph with version info. Do this in cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews. + +### Screenshots + +* 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 +* Screenshots should always only represent the most recent version, with very few exceptions that should be considered on a case-by-case basis. From 38a2ee8d6eef4f7a0efd340f456e66d9da8d9977 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:23:51 -0500 Subject: [PATCH 17/55] more --- docs/versions-types.md | 280 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 257 insertions(+), 23 deletions(-) diff --git a/docs/versions-types.md b/docs/versions-types.md index f2aee6e2..cb93d6b3 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -8,7 +8,7 @@ For example, we might document the serverless and v9 implementations of a featur This approach improves our documentation in several ways: -* When a user arrives in our documentation from an outside source, they'll be likelier to arrive on a page that applies to them. +* 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. @@ -22,30 +22,34 @@ Our approach might change as additional documentation features become available. :::{dropdown} Versioning facets There are multiple facets to versioning that we need to consider: -* **Elasticsearch flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **Stack ** +* **Elasticsearch / Kibana flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Stack Serverless") or **Stack ** + +% 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 ** Elasticsearch flavor. + All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. % TODO: Final term for "Self-managed" -* **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. E.G. clients, Elastic Common Schema +* **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 you’re viewing content that’s applicable to you. 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: +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 features are added both at the stack and the deployment level, both of these groups might be used together (e.g. security, user management, trust). +* 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 flavor. +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 represents organizational priorities. +However, we should all display our flavors and versions in the same order for consistency. This order reflects organizational priorities. **Flavors:** @@ -67,7 +71,7 @@ When it comes to hierarchy of versions, always put the newest version first. 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 release, or added in subsequent dot releases. Do not add version information to features added before these releases (e.g. features added in 8.16 don't need an 8.16 label or a 9.0 label). +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: @@ -89,11 +93,24 @@ This feature doesn't currently work - currently, only one label will appear. Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. +Choose from: +% this should become a quick-ref table + +* [Page-level `applies` tags](#page-level-applies-tags) +* [Section/heading-level `applies` tags](#sectionheading-level-applies-tags) +* [Inline `applies` tags](#inline-applies-tags) (currently just prose) +* [Tabs](#tabs) +* [Sibling bullets](#sibling-bullets) +* [Prose (inline)](#prose-inline) +* [Callouts](#callouts) +* [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections) +* [Sibling pages](#sibling-pages) + ### Page-level `applies` tags **Use case:** Provide signals that a page applies to the reader -**Number to use:** Minimum to add clarity +**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). **Approach:** @@ -101,25 +118,73 @@ 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** -TODO +#### 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 +:::{applies} +:ece: all +:hosted: all +:eck: all +:stack: all +::: + **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed -**Number to use:** Minimum to add clarity +**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). **When to use:** When the section-level scope differs from the page-level scope **Example** -TODO +See above ### Inline `applies` tags +::::{warning} +This feature doesn't currently work - we're working around it by using prose. +:::: + **Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version -**Number to use:** Three max. If the number of tags is longer than that, consider breaking up the list by facet. +**Number to use:** Three max. If the number of tags is longer than that, consider: + +* Breaking up the list by facet +* Using labels that don't have version / lifecycle information and deferring that information to the page or section for the feature + +Currently, we don't have inline `applies` tags. Instead, append the information to the bullet item in bolded square brackets `**[]**`. Add all information within a single set of square brackets. The brackets should appear after any final punctuation. + +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 + +Spaces let you organize your content and users according to your needs. + +::::{tab-set} +:group: one-two + +:::{tab-item} One +:sync: one + +* Each space has its own saved objects. +* Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. +* Each space has its own navigation. **[Stack v9 only]** + +::: +:::{tab-item} Two +:sync: two + + +* Learn about internal users, which are responsible for the operations that take place inside an Elasticsearch cluster +* Learn about service accounts, which are used for integration with external services that connect to Elasticsearch +* Learn about the services used for token-based authentication +* Learn about the services used by orchestrators **[Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes]** +* Learn about user lookup technologies +* Manage the user cache + +::: +:::: + ### Tabs @@ -127,15 +192,63 @@ TODO **Number to use:** Max 4 or 5 -Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose: +Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: -* “In version x and earlier, Spaces were referred to as Places.” -* “In version x and earlier, click the Permissions tab”. +* In version 9.1 and earlier, **Spaces** were referred to as **Places**. +* + ::::{note} + In version 9.1 and earlier, click the **Permissions** tab. + :::: Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. Consider breaking up procedures into sets of procedures if only one section differs between contexts. +#### Example + +To create a space: + +:::::{tab-set} +:group: stack-serverless + +::::{tab-item} Serverless +:sync: serverless + +1. Click **Create space** or select the space you want to edit. +2. Provide: + + * A meaningful name and description for the space. + * A URL identifier. The URL identifier is a short text string that becomes part of the Kibana URL. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier later. + +3. Customize the avatar of the space to your liking. +4. Save the space. +:::: + +::::{tab-item} Stack v9 +:sync: stack + +1. Select **Create space** and provide a name, description, and URL identifier. + The URL identifier is a short text string that becomes part of the Kibana URL when you are inside that space. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier once you create the space. + +2. Select a **Solution view**. This setting controls the navigation that all users of the space will get: + * **Search**: A light navigation menu focused on analytics and Search use cases. Features specific to Observability and Security are hidden. + * **Observability**: A light navigation menu focused on analytics and Observability use cases. Features specific to Search and Security are hidden. + * **Security**: A light navigation menu focused on analytics and Security use cases. Features specific to Observability and Search are hidden. + * **Classic**: All features from all solutions are visible by default using the classic, multilayered navigation menus. You can customize which features are visible individually. + +3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. + + :::{note} + Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure [Kibana Security](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). + ::: +4. Customize the avatar of the space to your liking. +5. Save your new space by selecting **Create space**. +:::: + +::::: + +You can edit all of the space settings you just defined at any time, except for the URL identifier. + ### Sibling bullets **Use case:** Requirements, limits, other simple, mirrored facts. @@ -144,26 +257,147 @@ Consider breaking up procedures into sets of procedures if only one section diff #### Examples +::::{tab-set} +:group: one-two + +:::{tab-item} One +:sync: one + ##### Required permissions * **Serverless**: `Admin` or equivalent * **Stack v9**: `kibana_admin` or equivalent +::: +:::{tab-item} Two +:sync: two + ##### Create a space The maximum number of spaces that you can have differs by [what do we call this]: * **Serverless**: Maximum of 100 spaces. * **Stack v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. +::: +:::: -##### Prose (inline) +### Prose (inline) **Use case:** Clarifying or secondary information -Sometimes, you can just preface a paragraph with version info. Do this in cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews. +**Number to use:** ~ once per section (use your judgement) + +**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews + +Sometimes, you can just preface a paragraph with version info. + +#### 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 + +**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 + +* *In **Manage TLS certificates** section*: + + :::{tip} + Elastic Cloud manages TLS certificates for you. + ::: + +* *In a **Spaces** overview* + + :::{note} + In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**. + +### Prose (explanatory paragraphs and sections) + +**Use case**: Differences with a "why" + +**When to use:** Comparative overviews + +Sometimes, a close explanation of the differences between things helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. + +You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. + +#### Example + +::::{tab-set} +:group: one-two + +:::{tab-item} One +:sync: one + +The way that TLS certificates are managed depends on your deployment type: + +In **self-managed Elasticsearch**, you manage both of these certificates yourself. + +In **Elastic Cloud on Kubernetes**, you can manage certificates for the HTTP layer. Certificates for the transport layer are managed by ECK and can’t be changed. However, you can set your own certificate authority, customize certificate contents, and provide your own certificate generation tools using transport settings. + +In **Elastic Cloud Enterprise**, you can use one or more proxy certificates to secure the HTTP layer. These certificates are managed at the ECE installation level. Transport-level encryption is managed by ECE and certificates can’t be changed. +::: + +:::{tab-item} Two +:sync: two + +**Managed security in Elastic Cloud** + +Elastic Cloud has built-in security. For example, HTTPS communications between Elastic Cloud and the internet, as well as inter-node communications, are secured automatically, and cluster data is encrypted at rest. + +You can augment Elastic Cloud security features in the following ways: + +* Configure traffic filtering to prevent unauthorized access to your deployments. +* Encrypt your deployment with a customer-managed encryption key. +* Secure your settings with the Elasticsearch keystore. +* Allow or deny Cloud IP ranges using Elastic Cloud static IPs. + +[Learn more about security measures in Elastic Cloud](https://www.elastic.co/cloud/security). + +::: +:::: + +You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. + +### Sibling pages + +**Use case:** + +* Processes that have significant differences **across multiple procedures** +* Chained procedures where not all of the procedures are needed for all contexts / where the flow across procedures is muddied when versioning context is added +* Very complex pages that are already heavily using tabs and other tools we use for versioning differences, making it hard to add another “layer” of content +* Beta to GA transitions? Hide the beta doc and leave it linked to the GA doc, which will presumably be more stable? + +**Number to use:** As few as possible. Consider leveraging other ways of communicating versioning differences to reduce the number of sibling pages. + +**When to use:** + +When version differences are just too large to be handled with any of our other tools. Try to avoid creating sibling pages when you can. + +% Down the line, if we need to, we could easily convert version-sensitive sibling pages into “picker” pages + +#### 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 -* 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 -* Screenshots should always only represent the most recent version, with very few exceptions that should be considered on a case-by-case basis. +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. From e360e40059d8f123ac54d5d41ccda671609dceb9 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:27:13 -0500 Subject: [PATCH 18/55] add project type --- docs/versions-types.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/versions-types.md b/docs/versions-types.md index cb93d6b3..2fed1e50 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -29,6 +29,8 @@ There are multiple facets to versioning that we need to consider: All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. +* **Project type:** The Serverless project types where a feature can be used. + % TODO: Final term for "Self-managed" * **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. From 5bffa52a9ebed4670ffe9858252d4e8acd06bd7c Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:28:52 -0500 Subject: [PATCH 19/55] move note --- docs/versions-types.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/versions-types.md b/docs/versions-types.md index 2fed1e50..1a011c31 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -29,9 +29,10 @@ There are multiple facets to versioning that we need to consider: All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. +% TODO: Final term for "Self-managed" + * **Project type:** The Serverless project types where a feature can be used. -% TODO: Final term for "Self-managed" * **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. E.g. clients, Elastic Common Schema From 85efd020a8a54c2c167cb218940485c29b4cd786 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:31:15 -0500 Subject: [PATCH 20/55] remove broken link --- docs/versions-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions-types.md b/docs/versions-types.md index 1a011c31..a9c7e8c2 100644 --- a/docs/versions-types.md +++ b/docs/versions-types.md @@ -242,7 +242,7 @@ To create a space: 3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. :::{note} - Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure [Kibana Security](/deploy-manage/users-roles/cluster-or-deployment-auth/built-in-roles.md). + Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure Kibana Security. ::: 4. Customize the avatar of the space to your liking. 5. Save your new space by selecting **Create space**. From 418000d3ebb2a63b4220552638ad36067efa014e Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:43:25 -0500 Subject: [PATCH 21/55] reorg --- docs/docset.yml | 5 +- .../content-patterns.md} | 143 +++--------------- docs/versions/index.md | 120 +++++++++++++++ 3 files changed, 145 insertions(+), 123 deletions(-) rename docs/{versions-types.md => versions/content-patterns.md} (68%) create mode 100644 docs/versions/index.md diff --git a/docs/docset.yml b/docs/docset.yml index 02d18d65..f2094577 100644 --- a/docs/docset.yml +++ b/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 diff --git a/docs/versions-types.md b/docs/versions/content-patterns.md similarity index 68% rename from docs/versions-types.md rename to docs/versions/content-patterns.md index a9c7e8c2..32e39fc0 100644 --- a/docs/versions-types.md +++ b/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 ** - -% 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 ** 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,13 +161,13 @@ 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 @@ -266,7 +175,7 @@ You can edit all of the space settings you just defined at any time, except for :::{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,14 +203,14 @@ 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 @@ -309,7 +218,7 @@ Some sections don’t apply to, say, Serverless, because we manage the headache 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) \ No newline at end of file diff --git a/docs/versions/index.md b/docs/versions/index.md new file mode 100644 index 00000000..b82540f2 --- /dev/null +++ b/docs/versions/index.md @@ -0,0 +1,120 @@ +--- +navigation_title: "Versions and types" +--- +# 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 + +### 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 ** + +% TODO: Final term for "Stack" +* **Deployment type:** The way Elastic is deployed: + * **Serverless** (sometimes "Elastic Stack Serverless") + * **Elastic Cloud Hosted** + * **Elastic Cloud on Kubernetes** + * **Elastic Cloud Enterprise** + * **Self-managed** + + All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. + +% TODO: Final term for "Self-managed" + +* **Project type:** The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability**. + +* **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. + +### 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. + +### 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 + +Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. + +Choose from: +% this should become a quick-ref table + +* [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) +* [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) +* [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) +* [Tabs](/versions/content-patterns.md#tabs) +* [Sibling bullets](/versions/content-patterns.md#sibling-bullets) +* [Prose (inline)](/versions/content-patterns.md#prose-inline) +* [Callouts](/versions/content-patterns.md#callouts) +* [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) +* [Sibling pages](/versions/content-patterns.md#sibling-pages) + +## 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. From b5929d5837ba61958737001a5ee1c47fbfcecd07 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:47:20 -0500 Subject: [PATCH 22/55] hello --- docs/versions/content-patterns.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 32e39fc0..0252bb52 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -1,5 +1,11 @@ --- navigation_title: "Content patterns" +applies: + stack: all + serverless: all + hosted: all + eck: all + ece: all --- # Version content patterns @@ -20,6 +26,8 @@ Choose from: ## Page-level `applies` tags +*see [`applies`](/syntax/applies.md)* + **Use case:** Provide signals that a page applies to the reader **Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). @@ -41,6 +49,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these :stack: all ::: +*see [`applies`](/syntax/applies.md#section)* **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed @@ -226,7 +235,7 @@ If there’s a terminology change or other minor change (especially where x equa Elastic Cloud manages TLS certificates for you. ::: -* *In a **Spaces** overview* +* *In a **Spaces** overview*: :::{note} In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**. From a05cfa6604fd898969f6b282602ba7fd2c9961a2 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:49:15 -0500 Subject: [PATCH 23/55] fixie linkie --- docs/versions/content-patterns.md | 4 ++-- docs/versions/index.md | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 0252bb52..720e15b6 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -30,7 +30,7 @@ Choose from: **Use case:** Provide signals that a page applies to the reader -**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). **Approach:** @@ -53,7 +53,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed -**Number to use:** Minimum to add clarity. See [basic concepts and principles](#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). **When to use:** When the section-level scope differs from the page-level scope diff --git a/docs/versions/index.md b/docs/versions/index.md index b82540f2..3957056e 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -19,6 +19,10 @@ Our approach might change as additional documentation features become available. ## Basic concepts and principles +* [Versioning facets](#versioning-facets) +* [Defaults and hierarchy](#defaults-and-hierarchy) +* [Versions and lifecycle states](#versions-and-lifecycle-states) + ### Versioning facets There are multiple facets to versioning that we need to consider: From 8a896651f1e69feca3ee98013dbbab47f4a344ef Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:51:22 -0500 Subject: [PATCH 24/55] fixie another linkie" --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 720e15b6..da1038d5 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -49,7 +49,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these :stack: all ::: -*see [`applies`](/syntax/applies.md#section)* +*see [`applies`](/syntax/applies.md#sections)* **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed From 1d711a78b4d2d073dae6b8e20fb3f45c44d817a6 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:52:27 -0500 Subject: [PATCH 25/55] it's my first day, ok? --- docs/docset.yml | 2 +- docs/versions/content-patterns.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docset.yml b/docs/docset.yml index f2094577..57fbf6fb 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -95,7 +95,7 @@ toc: - folder: versions - children: - file: index.md - - file: version-components.md + - file: content-patterns.md # nested TOCs are only allowed from docset.yml # to prevent them from being nested deeply arbitrarily - toc: development diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index da1038d5..3db2a4dd 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -30,7 +30,7 @@ Choose from: **Use case:** Provide signals that a page applies to the reader -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). **Approach:** @@ -53,7 +53,7 @@ See **Versions and lifecycle states** to learn when to specify versions in these **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.html#basic-concepts-and-principles). +**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). **When to use:** When the section-level scope differs from the page-level scope From b6fb27c8fd6044a60e02cb61493a6e56596d30c2 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 13:59:32 -0500 Subject: [PATCH 26/55] try this --- docs/docset.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docset.yml b/docs/docset.yml index 57fbf6fb..4db50d20 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -93,7 +93,7 @@ toc: - file: tagged_regions.md - file: titles.md - folder: versions - - children: + children: - file: index.md - file: content-patterns.md # nested TOCs are only allowed from docset.yml From 9b60757122584de3c9eb8b894d59aced48d413ee Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:19:50 -0500 Subject: [PATCH 27/55] add elastic.dev to external hosts --- docs/docset.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docset.yml b/docs/docset.yml index 4db50d20..cb3a28c6 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -20,6 +20,7 @@ external_hosts: - commonmark.org - github.io - github.com + - elastic.dev exclude: - '_*.md' subs: From 78e2c13ac71cfee5ca0786136e7a22c5f42603f4 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:27:26 -0500 Subject: [PATCH 28/55] cloud, not stack --- docs/versions/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 3957056e..d3044b2a 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -26,11 +26,11 @@ Our approach might change as additional documentation features become available. ### 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 ** +* **Elasticsearch / Kibana flavor:** The feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **Stack ** % TODO: Final term for "Stack" * **Deployment type:** The way Elastic is deployed: - * **Serverless** (sometimes "Elastic Stack Serverless") + * **Serverless** (sometimes "Elastic Cloud Serverless") * **Elastic Cloud Hosted** * **Elastic Cloud on Kubernetes** * **Elastic Cloud Enterprise** From 1c4dd6d35dc2d96d9807ad36087d1b521fe5b66b Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:29:59 -0500 Subject: [PATCH 29/55] fix weird order --- docs/versions/content-patterns.md | 35 +++++++++++++++---------------- docs/versions/index.md | 2 +- 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 3db2a4dd..4bfe1890 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -19,8 +19,8 @@ Choose from: * [Inline `applies` tags](#inline-applies-tags) (currently just prose) * [Tabs](#tabs) * [Sibling bullets](#sibling-bullets) -* [Prose (inline)](#prose-inline) * [Callouts](#callouts) +* [Prose (inline)](#prose-inline) * [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections) * [Sibling pages](#sibling-pages) @@ -202,23 +202,6 @@ The maximum number of spaces that you can have differs by [what do we call this] ::: :::: -## Prose (inline) - -**Use case:** Clarifying or secondary information - -**Number to use:** ~ once per section (use your judgement) - -**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews - -Sometimes, you can just preface a paragraph with version info. - -### 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 **Use case:** Happy differences, clarifications @@ -240,6 +223,22 @@ 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 (inline) + +**Use case:** Clarifying or secondary information + +**Number to use:** ~ once per section (use your judgement) + +**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews + +Sometimes, you can just preface a paragraph with version info. + +### 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. + ## Prose (explanatory paragraphs and sections) **Use case**: Differences with a "why" diff --git a/docs/versions/index.md b/docs/versions/index.md index d3044b2a..30ef0da4 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -108,8 +108,8 @@ Choose from: * [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) * [Tabs](/versions/content-patterns.md#tabs) * [Sibling bullets](/versions/content-patterns.md#sibling-bullets) -* [Prose (inline)](/versions/content-patterns.md#prose-inline) * [Callouts](/versions/content-patterns.md#callouts) +* [Prose (inline)](/versions/content-patterns.md#prose-inline) * [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) * [Sibling pages](/versions/content-patterns.md#sibling-pages) From 91bfbe1359988a6acae26e20621c39a1c9ee2ce4 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Mon, 10 Feb 2025 14:32:01 -0500 Subject: [PATCH 30/55] more --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 4bfe1890..cb625f45 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -111,7 +111,7 @@ Spaces let you organize your content and users according to your needs. **Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. -**Number to use:** Max 4 or 5 +**Number to use:** Max 4 or 5 (in a deployment type / versioning context - might be different for other situations) Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: From aac72a291c33c846a2698cbd4bc45416569d28d5 Mon Sep 17 00:00:00 2001 From: lcawl Date: Mon, 10 Feb 2025 22:10:06 -0800 Subject: [PATCH 31/55] Use substitutions for tab labels --- docs/versions/content-patterns.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index cb625f45..584a4d29 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -6,6 +6,10 @@ applies: hosted: all eck: all ece: all +subs: + stack: "Elastic Stack" + serverless-tab: "Elastic Cloud Serverless" + stack-all-tab: "All Elastic Stack" --- # Version content patterns @@ -132,7 +136,7 @@ To create a space: :::::{tab-set} :group: stack-serverless -::::{tab-item} Serverless +::::{tab-item} {{serverless-tab}} :sync: serverless 1. Click **Create space** or select the space you want to edit. @@ -145,7 +149,7 @@ To create a space: 4. Save the space. :::: -::::{tab-item} Stack v9 +::::{tab-item} {{stack-all-tab}} :sync: stack 1. Select **Create space** and provide a name, description, and URL identifier. From 0a0a6ca55803c29cb2fa7a94846981d6cd43306b Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:09:40 -0500 Subject: [PATCH 32/55] Update docs/versions/content-patterns.md Co-authored-by: Lisa Cawley --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 584a4d29..989e0715 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -40,7 +40,7 @@ Choose from: Add tags for all **versioning facets** relevant to the page. -See **Versions and lifecycle states** to learn when to specify versions in these tags. +See [Versions and lifecycle states](/versions/index.md#versions-and-lifecycle-states) to learn when to specify versions in these tags. ### Example [Manage your Cloud organization](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization.html) From d51f2eb0977874e01a8303605299936d4f8ee277 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:13:26 -0500 Subject: [PATCH 33/55] Update docs/versions/content-patterns.md Co-authored-by: Lisa Cawley --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 989e0715..bb518994 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -225,7 +225,7 @@ If there’s a terminology change or other minor change (especially where x equa * *In a **Spaces** overview*: :::{note} - In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**. + In {{stack}} versions 9.0 and earlier, **Spaces** are referred to as **Places**. ## Prose (inline) From 74959f6fd55363148b7fd96b85e564e3c9075b37 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:14:10 -0500 Subject: [PATCH 34/55] Update docs/versions/content-patterns.md Co-authored-by: florent-leborgne --- docs/versions/content-patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index bb518994..621efccf 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -43,7 +43,7 @@ Add tags for all **versioning facets** relevant to the page. See [Versions and lifecycle states](/versions/index.md#versions-and-lifecycle-states) to learn when to specify versions in these tags. ### Example -[Manage your Cloud organization](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization.html) +[Manage your Cloud organization](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization) ### Section/heading-level `applies` tags :::{applies} From bff37404df046b2d91407006376ac0df7c9a8dcf Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:20:16 -0500 Subject: [PATCH 35/55] Update docs/versions/index.md Co-authored-by: florent-leborgne --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 30ef0da4..f6bbb279 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -50,7 +50,7 @@ There are multiple facets to versioning that we need to consider: 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). +* 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, and trust features differ both at the deployment level and at the stack version level). * 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. From 7ec94302bd8f0fd7ebc34d8ca8b1c84bb393424c Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:21:13 -0500 Subject: [PATCH 36/55] Update docs/versions/index.md Co-authored-by: Lisa Cawley --- docs/versions/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/versions/index.md b/docs/versions/index.md index f6bbb279..42849dc8 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -36,6 +36,11 @@ There are multiple facets to versioning that we need to consider: * **Elastic Cloud Enterprise** * **Self-managed** +:::{warning} +The self-managed deployment type and support for products or platforms other than Elastic Stack does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) +::: + + All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. % TODO: Final term for "Self-managed" From c400293fe02c1636a654b6e5a71f6d224f379815 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:21:53 -0500 Subject: [PATCH 37/55] Update docs/versions/index.md Co-authored-by: florent-leborgne --- docs/versions/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/versions/index.md b/docs/versions/index.md index 42849dc8..5a8739f1 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -127,3 +127,4 @@ Follow these principles to use screenshots in our unversioned documentation syst * 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. +* In case of doubt, prioritize serverless. From a2023d686418a8324b9294cf50222154b2c9b158 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:23:57 -0500 Subject: [PATCH 38/55] Update docs/versions/index.md Co-authored-by: florent-leborgne --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 5a8739f1..714ca36c 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -41,7 +41,7 @@ The self-managed deployment type and support for products or platforms other tha ::: - All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. + All deployment types other than **Serverless** are used to run a **Stack ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. % TODO: Final term for "Self-managed" From 4033b03fff4f046d5d66b0a73ffffc83013ccb15 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 09:25:23 -0500 Subject: [PATCH 39/55] Update docs/versions/content-patterns.md --- docs/versions/content-patterns.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 621efccf..24de40f1 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -241,8 +241,6 @@ Sometimes, you can just preface a paragraph with version info. 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. - ## Prose (explanatory paragraphs and sections) **Use case**: Differences with a "why" From 354f4eb48aa4f6c948a60fdc6d584b0b995c9e06 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 10:15:52 -0500 Subject: [PATCH 40/55] Apply suggestions from code review Co-authored-by: florent-leborgne --- docs/versions/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 714ca36c..b3540c85 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -26,7 +26,7 @@ Our approach might change as additional documentation features become available. ### 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 Cloud Serverless") or **Stack ** +* **Stack flavor:** The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **Stack ** % TODO: Final term for "Stack" * **Deployment type:** The way Elastic is deployed: @@ -61,7 +61,7 @@ The role of these labels is providing a trust signal that the reader is viewing ### Defaults and hierarchy -You should not assume a default deployment type or Elasticsearch / Kibana flavor. +Do not assume a default deployment type, stack flavor, product version, or project type. Treat all flavors and deployment types equally. Don't treat one as the "base" and the other as the "exception". From 5459f1253c5e6a34d7b37b42798333c101005d4f Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 10:16:51 -0500 Subject: [PATCH 41/55] Update docs/versions/content-patterns.md Co-authored-by: Lisa Cawley --- docs/versions/content-patterns.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 24de40f1..f318f77b 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -129,6 +129,9 @@ 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. +:::{tip} +For consistency, use [substitutions](/syntax/substitutions.md) for the tab labels. +::: ### Example To create a space: From 30c134a04d91f5286dbdd46a4d8bee15f305271c Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 11:56:59 -0500 Subject: [PATCH 42/55] cleanup --- docs/docset.yml | 4 +- .../_snippets/content-patterns-list.md | 11 + docs/versions/content-patterns.md | 368 +----------------- docs/versions/index.md | 145 +------ .../CodeBlocks/CallOutTests.cs | 2 +- 5 files changed, 42 insertions(+), 488 deletions(-) create mode 100644 docs/versions/_snippets/content-patterns-list.md diff --git a/docs/docset.yml b/docs/docset.yml index 7373f4cf..594add2d 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -25,6 +25,8 @@ exclude: - '_*.md' subs: a-global-variable: "This was defined in docset.yml" + stack-short: Stack + serverless-short: Serverless toc: - file: index.md - hidden: developer-notes.md @@ -117,4 +119,4 @@ toc: - file: bar.md - folder: baz children: - - file: qux.md + - file: qux.md \ No newline at end of file diff --git a/docs/versions/_snippets/content-patterns-list.md b/docs/versions/_snippets/content-patterns-list.md new file mode 100644 index 00000000..dfb369af --- /dev/null +++ b/docs/versions/_snippets/content-patterns-list.md @@ -0,0 +1,11 @@ +| Approach | Use case | +| --- | --- | +| [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) | Provide signals that a page applies to the reader. | +| [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. | +| [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. | +| [Tabs](/versions/content-patterns.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. | +| [Sibling bullets](/versions/content-patterns.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. | +| [Callouts](/versions/content-patterns.md#callouts) | Draw attention to happy differences and basic clarifications. | +| [Prose (inline)](/versions/content-patterns.md#prose-inline) | Provide clarifying or secondary information. | +| [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) | Explain differences with a "why". | +| [Sibling pages](/versions/content-patterns.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. | \ No newline at end of file diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 9cbdc3d7..155ede4d 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -1,32 +1,15 @@ --- navigation_title: "Content patterns" -applies: - stack: all - serverless: all - hosted: all - eck: all - ece: all -subs: - stack: "Elastic Stack" - serverless-tab: "Elastic Cloud Serverless" - stack-all-tab: "All Elastic Stack" --- + # 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. Choose from: -% this should become a quick-ref table - -* [Page-level `applies` tags](#page-level-applies-tags) -* [Section/heading-level `applies` tags](#sectionheading-level-applies-tags) -* [Inline `applies` tags](#inline-applies-tags) (currently just prose) -* [Tabs](#tabs) -* [Sibling bullets](#sibling-bullets) -* [Callouts](#callouts) -* [Prose (inline)](#prose-inline) -* [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections) -* [Sibling pages](#sibling-pages) + +:::{include} _snippets/content-patterns-list.md +::: ## Page-level `applies` tags @@ -45,7 +28,8 @@ See [Versions and lifecycle states](/versions/index.md#versions-and-lifecycle-st ### Example [Manage your Cloud organization](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization) -### Section/heading-level `applies` tags +## Section/heading-level `applies` tags + :::{applies} :ece: all :hosted: all @@ -93,7 +77,7 @@ Spaces let you organize your content and users according to your needs. * Each space has its own saved objects. * Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. -* Each space has its own navigation. **[Stack v9 only]** +* Each space has its own navigation. **[{{stack-short}} v9 only]** ::: :::{tab-item} Two @@ -119,10 +103,10 @@ Spaces let you organize your content and users according to your needs. Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: -* In version 9.1 and earlier, **Spaces** were referred to as **Places**. +* In {{stack-short}} v9.1 and earlier, **Spaces** were referred to as **Places**. * ::::{note} - In version 9.1 and earlier, click the **Permissions** tab. + In {{stack-short}} v9.1 and earlier, click the **Permissions** tab. :::: Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. @@ -137,9 +121,9 @@ For consistency, use [substitutions](/syntax/substitutions.md) for the tab label To create a space: :::::{tab-set} -:group: stack-serverless +:group: serverless-stack -::::{tab-item} {{serverless-tab}} +::::{tab-item} {{serverless-short}} :sync: serverless 1. Click **Create space** or select the space you want to edit. @@ -152,7 +136,7 @@ To create a space: 4. Save the space. :::: -::::{tab-item} {{stack-all-tab}} +::::{tab-item} {{stack-short}} v9 :sync: stack 1. Select **Create space** and provide a name, description, and URL identifier. @@ -193,8 +177,8 @@ You can edit all of the space settings you just defined at any time, except for #### Required permissions -* **Serverless**: `Admin` or equivalent -* **Stack v9**: `kibana_admin` or equivalent +* **{{serverless-short}}**: `Admin` or equivalent +* **{{stack-short}} v9**: `kibana_admin` or equivalent ::: :::{tab-item} Two @@ -204,8 +188,8 @@ You can edit all of the space settings you just defined at any time, except for The maximum number of spaces that you can have differs by [what do we call this]: -* **Serverless**: Maximum of 100 spaces. -* **Stack v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. +* **{{serverless-short}}**: Maximum of 100 spaces. +* **{{stack-short}} v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. ::: :::: @@ -213,7 +197,7 @@ The maximum number of spaces that you can have differs by [what do we call this] **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. +Some sections don’t apply to contexts like 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. @@ -228,7 +212,7 @@ If there’s a terminology change or other minor change (especially where x equa * *In a **Spaces** overview*: :::{note} - In {{stack}} versions 9.0 and earlier, **Spaces** are referred to as **Places**. + In {{stack-short}} versions 9.0 and earlier, **Spaces** are referred to as **Places**. ## Prose (inline) @@ -242,319 +226,7 @@ Sometimes, you can just preface a paragraph with version info. ### 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. - -## Prose (explanatory paragraphs and sections) - -**Use case**: Differences with a "why" - -**When to use:** Comparative overviews - -Sometimes, a close explanation of the differences between things helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. - -You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. - -### Example - -::::{tab-set} -:group: one-two - -:::{tab-item} One -:sync: one - -The way that TLS certificates are managed depends on your deployment type: - -In **self-managed Elasticsearch**, you manage both of these certificates yourself. - -In **Elastic Cloud on Kubernetes**, you can manage certificates for the HTTP layer. Certificates for the transport layer are managed by ECK and can’t be changed. However, you can set your own certificate authority, customize certificate contents, and provide your own certificate generation tools using transport settings. - -In **Elastic Cloud Enterprise**, you can use one or more proxy certificates to secure the HTTP layer. These certificates are managed at the ECE installation level. Transport-level encryption is managed by ECE and certificates can’t be changed. -::: - -:::{tab-item} Two -:sync: two - -**Managed security in Elastic Cloud** - -Elastic Cloud has built-in security. For example, HTTPS communications between Elastic Cloud and the internet, as well as inter-node communications, are secured automatically, and cluster data is encrypted at rest. - -You can augment Elastic Cloud security features in the following ways: - -* Configure traffic filtering to prevent unauthorized access to your deployments. -* Encrypt your deployment with a customer-managed encryption key. -* Secure your settings with the Elasticsearch keystore. -* Allow or deny Cloud IP ranges using Elastic Cloud static IPs. - -[Learn more about security measures in Elastic Cloud](https://www.elastic.co/cloud/security). - -::: -:::: - -You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. - -## Sibling pages - -**Use case:** - -* Processes that have significant differences **across multiple procedures** -* Chained procedures where not all of the procedures are needed for all contexts / where the flow across procedures is muddied when versioning context is added -* Very complex pages that are already heavily using tabs and other tools we use for versioning differences, making it hard to add another “layer” of content -* Beta to GA transitions? Hide the beta doc and leave it linked to the GA doc, which will presumably be more stable? - -**Number to use:** As few as possible. Consider leveraging other ways of communicating versioning differences to reduce the number of sibling pages. - -**When to use:** - -When version differences are just too large to be handled with any of our other tools. Try to avoid creating sibling pages when you can. - -% Down the line, if we need to, we could easily convert version-sensitive sibling pages into “picker” pages - -### 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)--- -navigation_title: "Content patterns" -applies: - stack: all - serverless: all - hosted: all - eck: all - ece: all ---- -# 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. - -Choose from: -% this should become a quick-ref table - -* [Page-level `applies` tags](#page-level-applies-tags) -* [Section/heading-level `applies` tags](#sectionheading-level-applies-tags) -* [Inline `applies` tags](#inline-applies-tags) (currently just prose) -* [Tabs](#tabs) -* [Sibling bullets](#sibling-bullets) -* [Callouts](#callouts) -* [Prose (inline)](#prose-inline) -* [Prose (explanatory paragraphs and sections)](#prose-explanatory-paragraphs-and-sections) -* [Sibling pages](#sibling-pages) - -## Page-level `applies` tags - -*see [`applies`](/syntax/applies.md)* - -**Use case:** Provide signals that a page applies to the reader - -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). - -**Approach:** - -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 -[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 -:::{applies} -:ece: all -:hosted: all -:eck: all -:stack: all -::: - -*see [`applies`](/syntax/applies.md#sections)* - -**Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed - -**Number to use:** Minimum to add clarity. See [basic concepts and principles](/versions/index.md#basic-concepts-and-principles). - -**When to use:** When the section-level scope differs from the page-level scope - -**Example** -See above - -## Inline `applies` tags - -::::{warning} -This feature doesn't currently work - we're working around it by using prose. -:::: - -**Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version - -**Number to use:** Three max. If the number of tags is longer than that, consider: - -* Breaking up the list by facet -* Using labels that don't have version / lifecycle information and deferring that information to the page or section for the feature - -Currently, we don't have inline `applies` tags. Instead, append the information to the bullet item in bolded square brackets `**[]**`. Add all information within a single set of square brackets. The brackets should appear after any final punctuation. - -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 - -Spaces let you organize your content and users according to your needs. - -::::{tab-set} -:group: one-two - -:::{tab-item} One -:sync: one - -* Each space has its own saved objects. -* Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. -* Each space has its own navigation. **[Stack v9 only]** - -::: -:::{tab-item} Two -:sync: two - - -* Learn about internal users, which are responsible for the operations that take place inside an Elasticsearch cluster -* Learn about service accounts, which are used for integration with external services that connect to Elasticsearch -* Learn about the services used for token-based authentication -* Learn about the services used by orchestrators **[Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes]** -* Learn about user lookup technologies -* Manage the user cache - -::: -:::: - - -## Tabs - -**Use case:** When one or more steps in a process differs, put the steps into tabs - one for each process. - -**Number to use:** Max 4 or 5 (in a deployment type / versioning context - might be different for other situations) - -Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: - -* In version 9.1 and earlier, **Spaces** were referred to as **Places**. -* - ::::{note} - In version 9.1 and earlier, click the **Permissions** tab. - :::: - -Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. - -Consider breaking up procedures into sets of procedures if only one section differs between contexts. - -### Example - -To create a space: - -:::::{tab-set} -:group: stack-serverless - -::::{tab-item} Serverless -:sync: serverless - -1. Click **Create space** or select the space you want to edit. -2. Provide: - - * A meaningful name and description for the space. - * A URL identifier. The URL identifier is a short text string that becomes part of the Kibana URL. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier later. - -3. Customize the avatar of the space to your liking. -4. Save the space. -:::: - -::::{tab-item} Stack v9 -:sync: stack - -1. Select **Create space** and provide a name, description, and URL identifier. - The URL identifier is a short text string that becomes part of the Kibana URL when you are inside that space. Kibana suggests a URL identifier based on the name of your space, but you can customize the identifier to your liking. You cannot change the space identifier once you create the space. - -2. Select a **Solution view**. This setting controls the navigation that all users of the space will get: - * **Search**: A light navigation menu focused on analytics and Search use cases. Features specific to Observability and Security are hidden. - * **Observability**: A light navigation menu focused on analytics and Observability use cases. Features specific to Search and Security are hidden. - * **Security**: A light navigation menu focused on analytics and Security use cases. Features specific to Observability and Search are hidden. - * **Classic**: All features from all solutions are visible by default using the classic, multilayered navigation menus. You can customize which features are visible individually. - -3. If you selected the **Classic** solution view, you can customize the **Feature visibility** as you need it to be for that space. - - :::{note} - Even when disabled in this menu, some Management features can remain visible to some users depending on their privileges. Additionally, controlling feature visibility is not a security feature. To secure access to specific features on a per-user basis, you must configure Kibana Security. - ::: -4. Customize the avatar of the space to your liking. -5. Save your new space by selecting **Create space**. -:::: - -::::: - -You can edit all of the space settings you just defined at any time, except for the URL identifier. - -## 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 - -::::{tab-set} -:group: one-two - -:::{tab-item} One -:sync: one - -#### Required permissions - -* **Serverless**: `Admin` or equivalent -* **Stack v9**: `kibana_admin` or equivalent - -::: -:::{tab-item} Two -:sync: two - -#### Create a space - -The maximum number of spaces that you can have differs by [what do we call this]: - -* **Serverless**: Maximum of 100 spaces. -* **Stack v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. -::: -:::: - -## 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 - -* *In **Manage TLS certificates** section*: - - :::{tip} - Elastic Cloud manages TLS certificates for you. - ::: - -* *In a **Spaces** overview*: - - :::{note} - In Stack versions 9.0 and lower, **Spaces** are referred to as **Places**. - -## Prose (inline) - -**Use case:** Clarifying or secondary information - -**Number to use:** ~ once per section (use your judgement) - -**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews - -Sometimes, you can just preface a paragraph with version info. - -### 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. +If you're managing a {{stack-short}} v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. ## Prose (explanatory paragraphs and sections) @@ -627,4 +299,4 @@ When version differences are just too large to be handled with any of our other 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) \ No newline at end of file +[{{serverless-short}} project billing dimensions](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/deploy-manage/cloud-organization/billing/serverless-project-billing-dimensions.html) \ No newline at end of file diff --git a/docs/versions/index.md b/docs/versions/index.md index a39a431c..04144289 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -1,6 +1,7 @@ --- navigation_title: "Versions and types" --- + # 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. @@ -26,7 +27,7 @@ Our approach might change as additional documentation features become available. ### Versioning facets There are multiple facets to versioning that we need to consider: -* **Stack flavor:** The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **Stack ** +* **Stack flavor:** The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack-short}} ** % TODO: Final term for "Stack" * **Deployment type:** The way Elastic is deployed: @@ -37,11 +38,11 @@ There are multiple facets to versioning that we need to consider: * **Self-managed** :::{warning} -The self-managed deployment type and support for products or platforms other than Elastic Stack does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) +The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) ::: - All deployment types other than **Serverless** are used to run a **Stack ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. + All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. % TODO: Final term for "Self-managed" @@ -106,142 +107,9 @@ This feature doesn't currently work - currently, only one label will appear. Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. Choose from: -% this should become a quick-ref table - -* [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) -* [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) -* [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) -* [Tabs](/versions/content-patterns.md#tabs) -* [Sibling bullets](/versions/content-patterns.md#sibling-bullets) -* [Callouts](/versions/content-patterns.md#callouts) -* [Prose (inline)](/versions/content-patterns.md#prose-inline) -* [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) -* [Sibling pages](/versions/content-patterns.md#sibling-pages) - -## 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. -* In case of doubt, prioritize serverless. ---- -navigation_title: "Versions and types" ---- -# 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 - -* [Versioning facets](#versioning-facets) -* [Defaults and hierarchy](#defaults-and-hierarchy) -* [Versions and lifecycle states](#versions-and-lifecycle-states) - -### 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 Cloud Serverless") or **Stack ** - -% TODO: Final term for "Stack" -* **Deployment type:** The way Elastic is deployed: - * **Serverless** (sometimes "Elastic Cloud Serverless") - * **Elastic Cloud Hosted** - * **Elastic Cloud on Kubernetes** - * **Elastic Cloud Enterprise** - * **Self-managed** - - All deployment types other than **Serverless** use the **Stack ** flavor of Elasticsearch / Kibana. - -% TODO: Final term for "Self-managed" - -* **Project type:** The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability**. - -* **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. - -### 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. - -### 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 - -Depending on what you're trying to communicate, you can use the following patterns to represent version and deployment type differences in your docs. - -Choose from: -% this should become a quick-ref table - -* [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) -* [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) -* [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) -* [Tabs](/versions/content-patterns.md#tabs) -* [Sibling bullets](/versions/content-patterns.md#sibling-bullets) -* [Callouts](/versions/content-patterns.md#callouts) -* [Prose (inline)](/versions/content-patterns.md#prose-inline) -* [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) -* [Sibling pages](/versions/content-patterns.md#sibling-pages) +:::{include} _snippets/content-patterns-list.md +::: ## Best practices @@ -252,3 +120,4 @@ Follow these principles to use screenshots in our unversioned documentation syst * 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. +* In case of doubt, prioritize serverless. \ No newline at end of file diff --git a/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs b/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs index 564879e9..cf488896 100644 --- a/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs +++ b/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs @@ -253,7 +253,7 @@ public class ClassicCallOutWithTheRightListItems(ITestOutputHelper output) : Cod 5. Hostname and port of the APM Server endpoint. For example, elastic-apm-server:8200. 6. Credential for Elastic APM secret token authorization (Authorization: "Bearer a_secret_token") or API key authorization (Authorization: "ApiKey an_api_key"). 7. Environment-specific configuration parameters can be conveniently passed in as environment variables documented here (e.g. ELASTIC_APM_SERVER_ENDPOINT and ELASTIC_APM_SECRET_TOKEN). -8. [preview] To send OpenTelemetry logs to {stack} version 8.0+, declare a logs pipeline. +8. [preview] To send OpenTelemetry logs to {stack-short} version 8.0+, declare a logs pipeline. """ ) From afe95d3b8efdfc7f53065b850004f17152955240 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 12:05:57 -0500 Subject: [PATCH 43/55] more --- .../_snippets/content-patterns-list.md | 5 +-- docs/versions/content-patterns.md | 43 +++++++------------ 2 files changed, 18 insertions(+), 30 deletions(-) diff --git a/docs/versions/_snippets/content-patterns-list.md b/docs/versions/_snippets/content-patterns-list.md index dfb369af..327e7d6b 100644 --- a/docs/versions/_snippets/content-patterns-list.md +++ b/docs/versions/_snippets/content-patterns-list.md @@ -2,10 +2,9 @@ | --- | --- | | [Page-level `applies` tags](/versions/content-patterns.md#page-level-applies-tags) | Provide signals that a page applies to the reader. | | [Section/heading-level `applies` tags](/versions/content-patterns.md#sectionheading-level-applies-tags) | Provide signals about a section’s scope so a user can choose to read or skip it as needed. | -| [Inline `applies` tags](/versions/content-patterns.md#inline-applies-tags) (currently just prose) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. | +| [List item suffixes](/versions/content-patterns.md#list-item-suffixes) | Identify features in a **list of features** that are exclusive to a specific context, or that were introduced in a specific version. | | [Tabs](/versions/content-patterns.md#tabs) | Provide two sets of procedures when one or more steps in a process differs between contexts or versions. | | [Sibling bullets](/versions/content-patterns.md#sibling-bullets) | List differing requirements, limits, and other simple, mirrored facts. | | [Callouts](/versions/content-patterns.md#callouts) | Draw attention to happy differences and basic clarifications. | -| [Prose (inline)](/versions/content-patterns.md#prose-inline) | Provide clarifying or secondary information. | -| [Prose (explanatory paragraphs and sections)](/versions/content-patterns.md#prose-explanatory-paragraphs-and-sections) | Explain differences with a "why". | +| [Prose](/versions/content-patterns.md#prose) | Provide clarifying or secondary information, explain differences with a "why". | | [Sibling pages](/versions/content-patterns.md#sibling-pages) | When the information is too complex to be addressed with only the other content patterns. See specific examples in the sibling pages section. | \ No newline at end of file diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 155ede4d..06c7f3eb 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -48,11 +48,7 @@ See [Versions and lifecycle states](/versions/index.md#versions-and-lifecycle-st **Example** See above -## Inline `applies` tags - -::::{warning} -This feature doesn't currently work - we're working around it by using prose. -:::: +## List item suffixes **Use case:** When features in a **list of features** are exclusive to a specific context, or were introduced in a specific version @@ -61,9 +57,9 @@ This feature doesn't currently work - we're working around it by using prose. * Breaking up the list by facet * Using labels that don't have version / lifecycle information and deferring that information to the page or section for the feature -Currently, we don't have inline `applies` tags. Instead, append the information to the bullet item in bolded square brackets `**[]**`. Add all information within a single set of square brackets. The brackets should appear after any final punctuation. +**Approach:** -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. +Append the information to the bullet item in bolded square brackets `**[]**`. Add all information within a single set of square brackets. The brackets should appear after any final punctuation. Consider using words like `only` to help people to understand that this information indicates the applicability of a feature. ### Example @@ -214,34 +210,24 @@ If there’s a terminology change or other minor change (especially where x equa :::{note} In {{stack-short}} versions 9.0 and earlier, **Spaces** are referred to as **Places**. -## Prose (inline) - -**Use case:** Clarifying or secondary information - -**Number to use:** ~ once per section (use your judgement) - -**When to use:** Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews - -Sometimes, you can just preface a paragraph with version info. - -### Example - -If you're managing a {{stack-short}} v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. +## Prose -## Prose (explanatory paragraphs and sections) +**Use case**: Clarifying or secondary information, differences with a "why" -**Use case**: Differences with a "why" +**When to use:** +* Cases where the information isn’t wildly important, but nice to know, or to add basic terminology change info to overviews +* Comparative overviews -**When to use:** Comparative overviews +In some cases, you might want to add a paragraph specific to one version or another in prose to clarify behavior or terminology. -Sometimes, a close explanation of the differences between things helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. +In cases where there are significant differences between contexts, close explanation of the differences helps people to understand how something works, or why something behaves the way it does. Compare and contrast differences in paragraphs when the explanation helps people to use our features effectively. You also might do this to compare approaches between deployment types, when [sibling bullets](#sibling-bullets) aren't enough. ### Example ::::{tab-set} -:group: one-two +:group: one-two-three :::{tab-item} One :sync: one @@ -257,6 +243,11 @@ In **Elastic Cloud Enterprise**, you can use one or more proxy certificates to s :::{tab-item} Two :sync: two +If you're managing a {{stack-short}} v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. +::: + +:::{tab-item} Three +:sync: three **Managed security in Elastic Cloud** @@ -274,8 +265,6 @@ 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 **Use case:** From 4dd2fdbeeba29c9247a495e953c07b75cf41f94a Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 12:11:18 -0500 Subject: [PATCH 44/55] more --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 04144289..bdbf62f4 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -58,7 +58,7 @@ The role of these labels is providing a trust signal that the reader is viewing * 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, and trust features differ both at the deployment level and at the stack version level). -* 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. +* In some sections, such as **Explore and analyze**, features generally only differ by stack flavor. In these cases, you can choose to include only this facet on the page. ### Defaults and hierarchy From 14d11ec82de492a26173334384e38a1d7aa8958d Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 13:04:30 -0500 Subject: [PATCH 45/55] indent --- docs/versions/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index bdbf62f4..fc3ad063 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -37,9 +37,9 @@ There are multiple facets to versioning that we need to consider: * **Elastic Cloud Enterprise** * **Self-managed** -:::{warning} -The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) -::: + :::{warning} + The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) + ::: All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. From ff0dd2c026b08812f4c32af305e5482cc37d2860 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 13:06:07 -0500 Subject: [PATCH 46/55] move note --- docs/versions/index.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index fc3ad063..6427d164 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -37,11 +37,6 @@ There are multiple facets to versioning that we need to consider: * **Elastic Cloud Enterprise** * **Self-managed** - :::{warning} - The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) - ::: - - All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. % TODO: Final term for "Self-managed" @@ -52,6 +47,10 @@ There are multiple facets to versioning that we need to consider: E.g. clients, Elastic Common Schema +:::{warning} +The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) +::: + **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: From 84f6861c8a8438544b7991e4d19fb72118458b64 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 13:08:53 -0500 Subject: [PATCH 47/55] it's a table now --- docs/versions/index.md | 28 +++++++++------------------- 1 file changed, 9 insertions(+), 19 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 6427d164..e78ca8e1 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -27,30 +27,20 @@ Our approach might change as additional documentation features become available. ### Versioning facets There are multiple facets to versioning that we need to consider: -* **Stack flavor:** The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack-short}} ** - -% TODO: Final term for "Stack" -* **Deployment type:** The way Elastic is deployed: - * **Serverless** (sometimes "Elastic Cloud Serverless") - * **Elastic Cloud Hosted** - * **Elastic Cloud on Kubernetes** - * **Elastic Cloud Enterprise** - * **Self-managed** - - All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. - -% TODO: Final term for "Self-managed" - -* **Project type:** The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability**. - -* **Other versioning schemes:** Elastic products or tools with a versioned component, where stack versioning is not followed. - - E.g. clients, Elastic Common Schema +| Facet | Description | +| --- | --- | +| **Stack flavor** | The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack-short}} ** | +| **Deployment type** | The way Elastic is deployed:

* **Serverless** (sometimes "Elastic Cloud Serverless")
* **Elastic Cloud Hosted**
* **Elastic Cloud on Kubernetes**
* **Elastic Cloud Enterprise**
* **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. +| **Project type** | The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability** | +| **Other versioning schemes** | Elastic products or tools with a versioned component, where stack versioning is not followed.

E.g. clients, Elastic Common Schema | :::{warning} The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) ::: +% TODO: Final term for "Stack" +% TODO: Final term for "Self-managed" + **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: From 76b9af974df1d426af0c013fe0be1ef857945ec7 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 13:09:19 -0500 Subject: [PATCH 48/55] with dashes --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index e78ca8e1..8038879a 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -30,7 +30,7 @@ There are multiple facets to versioning that we need to consider: | Facet | Description | | --- | --- | | **Stack flavor** | The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack-short}} ** | -| **Deployment type** | The way Elastic is deployed:

* **Serverless** (sometimes "Elastic Cloud Serverless")
* **Elastic Cloud Hosted**
* **Elastic Cloud on Kubernetes**
* **Elastic Cloud Enterprise**
* **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. +| **Deployment type** | The way Elastic is deployed:

- **Serverless** (sometimes "Elastic Cloud Serverless")
- **Elastic Cloud Hosted**
- **Elastic Cloud on Kubernetes**
- **Elastic Cloud Enterprise**
- **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. | **Project type** | The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability** | | **Other versioning schemes** | Elastic products or tools with a versioned component, where stack versioning is not followed.

E.g. clients, Elastic Common Schema | From 7f71ed6cb11d9cb537a7d065af44d74f50087ff0 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 13:09:55 -0500 Subject: [PATCH 49/55] v --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 8038879a..af251b43 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -60,7 +60,7 @@ However, we should all display our flavors and versions in the same order for co **Flavors:** 1. Serverless -2. Stack +2. Stack **Deployment types:** From 9a90891c52cd1d3565a123903625d35a2e9d2c5a Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 21:28:47 -0500 Subject: [PATCH 50/55] Update docs/versions/index.md Co-authored-by: Kaarina Tungseth --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index af251b43..bed838db 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -31,7 +31,7 @@ There are multiple facets to versioning that we need to consider: | --- | --- | | **Stack flavor** | The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack-short}} ** | | **Deployment type** | The way Elastic is deployed:

- **Serverless** (sometimes "Elastic Cloud Serverless")
- **Elastic Cloud Hosted**
- **Elastic Cloud on Kubernetes**
- **Elastic Cloud Enterprise**
- **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. -| **Project type** | The Serverless project types where a feature can be used - either **Elasticsearch**, **Security**, or **Observability** | +| **Project type** | The Serverless project types where a feature can be used - either **Elasticsearch**, **Elastic Security**, or **Elastic Observability** | | **Other versioning schemes** | Elastic products or tools with a versioned component, where stack versioning is not followed.

E.g. clients, Elastic Common Schema | :::{warning} From ab2a70515495785eceefdd9a1de3e6cc9f2d2640 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 21:37:13 -0500 Subject: [PATCH 51/55] Apply suggestions from code review Co-authored-by: Kaarina Tungseth --- docs/versions/content-patterns.md | 6 +++--- docs/versions/index.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 06c7f3eb..691a9239 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -99,10 +99,10 @@ Spaces let you organize your content and users according to your needs. Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: -* In {{stack-short}} v9.1 and earlier, **Spaces** were referred to as **Places**. +* In {{stack-short}} 9.1.0 and earlier, **Spaces** were referred to as **Places**. * ::::{note} - In {{stack-short}} v9.1 and earlier, click the **Permissions** tab. + In {{stack-short}} 9.1.0 and earlier, click the **Permissions** tab. :::: Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. @@ -208,7 +208,7 @@ If there’s a terminology change or other minor change (especially where x equa * *In a **Spaces** overview*: :::{note} - In {{stack-short}} versions 9.0 and earlier, **Spaces** are referred to as **Places**. + In {{stack-short}} 9.0.0 and earlier, **Spaces** are referred to as **Places**. ## Prose diff --git a/docs/versions/index.md b/docs/versions/index.md index bed838db..e0b1e901 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -4,8 +4,8 @@ navigation_title: "Versions and types" # 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. +In Elastic Docs v3, 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 Elastic Stack 9.0.0 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: @@ -76,7 +76,7 @@ When it comes to hierarchy of versions, always put the newest version first. 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. +Add version labels only when a feature was added as part of the major version release (e.g. 9.0.0), or added in subsequent minor releases (e.g. 9.1.0). Do not add version information to features added before these releases. For example, features added in 8.16.0 don't need an 8.16.0 label or a 9.0.0 label, but features added in 9.0.0 need a 9.0.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: From 50e5b8a25a24bf9a9cefe41c1cf9ed59d8e99bab Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 21:48:57 -0500 Subject: [PATCH 52/55] Apply suggestions from code review Co-authored-by: Kaarina Tungseth --- docs/versions/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index e0b1e901..2cec72f6 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -43,7 +43,7 @@ The self-managed deployment type and support for products or platforms other tha **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: +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 facet on pages where only one facet 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, and trust features differ both at the deployment level and at the stack version level). @@ -74,7 +74,7 @@ When it comes to hierarchy of versions, always put the newest version first. ### 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+). +In Elastic Docs v3, we currently document only our latest major versions (Elastic Stack 9.0.0, ECE 4.0.0 and later, ECK 3.0.0 and later). Add version labels only when a feature was added as part of the major version release (e.g. 9.0.0), or added in subsequent minor releases (e.g. 9.1.0). Do not add version information to features added before these releases. For example, features added in 8.16.0 don't need an 8.16.0 label or a 9.0.0 label, but features added in 9.0.0 need a 9.0.0 label. From 1aded31351c60fba583e694fa44ad4769098a324 Mon Sep 17 00:00:00 2001 From: shainaraskas Date: Tue, 11 Feb 2025 22:00:11 -0500 Subject: [PATCH 53/55] change sub --- docs/docset.yml | 2 +- docs/versions/content-patterns.md | 16 ++++++++-------- docs/versions/index.md | 6 +++--- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/docset.yml b/docs/docset.yml index 594add2d..d3548a31 100644 --- a/docs/docset.yml +++ b/docs/docset.yml @@ -25,7 +25,7 @@ exclude: - '_*.md' subs: a-global-variable: "This was defined in docset.yml" - stack-short: Stack + stack: Elastic Stack serverless-short: Serverless toc: - file: index.md diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index 691a9239..0b5a107a 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -73,7 +73,7 @@ Spaces let you organize your content and users according to your needs. * Each space has its own saved objects. * Users can only access the spaces that they have been granted access to. This access is based on user roles, and a given role can have different permissions per space. -* Each space has its own navigation. **[{{stack-short}} v9 only]** +* Each space has its own navigation. **[{{stack}} v9 only]** ::: :::{tab-item} Two @@ -99,10 +99,10 @@ Spaces let you organize your content and users according to your needs. Try to minimize the number of tabs where you can - try to work around small differences by rewording or adding context in prose or in `note` style admonitions: -* In {{stack-short}} 9.1.0 and earlier, **Spaces** were referred to as **Places**. +* In {{stack}} 9.1.0 and earlier, **Spaces** were referred to as **Places**. * ::::{note} - In {{stack-short}} 9.1.0 and earlier, click the **Permissions** tab. + In {{stack}} 9.1.0 and earlier, click the **Permissions** tab. :::: Try not to include information surrounding a procedure in the tabs. Make the tab content as small as possible apart from the procedure itself. @@ -132,7 +132,7 @@ To create a space: 4. Save the space. :::: -::::{tab-item} {{stack-short}} v9 +::::{tab-item} {{stack}} v9 :sync: stack 1. Select **Create space** and provide a name, description, and URL identifier. @@ -174,7 +174,7 @@ You can edit all of the space settings you just defined at any time, except for #### Required permissions * **{{serverless-short}}**: `Admin` or equivalent -* **{{stack-short}} v9**: `kibana_admin` or equivalent +* **{{stack}} v9**: `kibana_admin` or equivalent ::: :::{tab-item} Two @@ -185,7 +185,7 @@ You can edit all of the space settings you just defined at any time, except for The maximum number of spaces that you can have differs by [what do we call this]: * **{{serverless-short}}**: Maximum of 100 spaces. -* **{{stack-short}} v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. +* **{{stack}} v9**: Controlled by the `xpack.spaces.maxSpaces` setting. Default is 1000. ::: :::: @@ -208,7 +208,7 @@ If there’s a terminology change or other minor change (especially where x equa * *In a **Spaces** overview*: :::{note} - In {{stack-short}} 9.0.0 and earlier, **Spaces** are referred to as **Places**. + In {{stack}} 9.0.0 and earlier, **Spaces** are referred to as **Places**. ## Prose @@ -243,7 +243,7 @@ In **Elastic Cloud Enterprise**, you can use one or more proxy certificates to s :::{tab-item} Two :sync: two -If you're managing a {{stack-short}} v9 deployment, then you can also assign roles and define permissions for a space from the **Permissions** tab of the space settings. +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. ::: :::{tab-item} Three diff --git a/docs/versions/index.md b/docs/versions/index.md index 2cec72f6..170626f3 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -29,13 +29,13 @@ There are multiple facets to versioning that we need to consider: | Facet | Description | | --- | --- | -| **Stack flavor** | The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack-short}} ** | -| **Deployment type** | The way Elastic is deployed:

- **Serverless** (sometimes "Elastic Cloud Serverless")
- **Elastic Cloud Hosted**
- **Elastic Cloud on Kubernetes**
- **Elastic Cloud Enterprise**
- **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack-short}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. +| **Stack flavor** | The Elasticsearch or Kibana feature base used for basic functionality. Either **Serverless** (sometimes "Elastic Cloud Serverless") or **{{stack}} ** | +| **Deployment type** | The way Elastic is deployed:

- **Serverless** (sometimes "Elastic Cloud Serverless")
- **Elastic Cloud Hosted**
- **Elastic Cloud on Kubernetes**
- **Elastic Cloud Enterprise**
- **Self-managed**

All deployment types other than **Serverless** are used to run a **{{stack}} ** flavor of Elasticsearch / Kibana. ECK and ECE also have their own versioning. For example, one can run a v9.0.0 deployment on ECE 4.0. | **Project type** | The Serverless project types where a feature can be used - either **Elasticsearch**, **Elastic Security**, or **Elastic Observability** | | **Other versioning schemes** | Elastic products or tools with a versioned component, where stack versioning is not followed.

E.g. clients, Elastic Common Schema | :::{warning} -The self-managed deployment type and support for products or platforms other than {{stack-short}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) +The self-managed deployment type and support for products or platforms other than {{stack}} does not exist yet. Contribute to the discussion in [#452](https://github.com/elastic/docs-builder/discussions/452) ::: % TODO: Final term for "Stack" From 7fa5f3e7e98ea951494d2086d25185754f5cee70 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 22:00:58 -0500 Subject: [PATCH 54/55] Update tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs --- tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs b/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs index cf488896..564879e9 100644 --- a/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs +++ b/tests/Elastic.Markdown.Tests/CodeBlocks/CallOutTests.cs @@ -253,7 +253,7 @@ public class ClassicCallOutWithTheRightListItems(ITestOutputHelper output) : Cod 5. Hostname and port of the APM Server endpoint. For example, elastic-apm-server:8200. 6. Credential for Elastic APM secret token authorization (Authorization: "Bearer a_secret_token") or API key authorization (Authorization: "ApiKey an_api_key"). 7. Environment-specific configuration parameters can be conveniently passed in as environment variables documented here (e.g. ELASTIC_APM_SERVER_ENDPOINT and ELASTIC_APM_SECRET_TOKEN). -8. [preview] To send OpenTelemetry logs to {stack-short} version 8.0+, declare a logs pipeline. +8. [preview] To send OpenTelemetry logs to {stack} version 8.0+, declare a logs pipeline. """ ) From 63e0e645554bf126700496c58c0e9b5e5a1b0146 Mon Sep 17 00:00:00 2001 From: shainaraskas <58563081+shainaraskas@users.noreply.github.com> Date: Tue, 11 Feb 2025 22:09:04 -0500 Subject: [PATCH 55/55] Update docs/versions/index.md --- docs/versions/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versions/index.md b/docs/versions/index.md index 170626f3..1e91d0f3 100644 --- a/docs/versions/index.md +++ b/docs/versions/index.md @@ -78,7 +78,7 @@ In Elastic Docs v3, we currently document only our latest major versions (Elasti Add version labels only when a feature was added as part of the major version release (e.g. 9.0.0), or added in subsequent minor releases (e.g. 9.1.0). Do not add version information to features added before these releases. For example, features added in 8.16.0 don't need an 8.16.0 label or a 9.0.0 label, but features added in 9.0.0 need a 9.0.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: +From the latest major version release 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