[work in progress!!] Add best practices for applies_to

[colleenmcginnis]

Closes https://github.com/elastic/docs-content-internal/issues/55

⚠️ This is still a very rough PR and is not ready for review. ⚠️

I started collecting examples from across Slack and GitHub where the Docs team has been discussing how we should approach cumulative documentation in different scenarios. This will add a best practices doc outlining what I've found. There are some situations where I've found conflicting or incomplete advice. In those cases, I'll try to get consensus. 🙃

In this PR, I also moved the content in Versions and types closer to the docs on cumulative documentation.

[github-actions]

🔍 Preview links for changed docs

• docs/contribute/cumulative-docs/best-practices.md
• docs/contribute/cumulative-docs/reference.md
• docs/configure/site/versions.md
• docs/contribute/add-repo.md
• docs/contribute/branching-strategy.md
• docs/contribute/index.md
• docs/contribute/locally.md
• docs/migration/versioning.md
• docs/syntax/applies.md
• docs/syntax/quick-ref.md

More links …

• docs/contribute/cumulative-docs/content-patterns.md
• docs/contribute/cumulative-docs/index.md

[bmorelli25]

Here are some initial comments and suggestions. I still have a lot of content to go through. This is a great addition to the OG CD docs that Shaina created.

[bmorelli25]

I don't think anyone uses -rc1 versions other than the stack. And I don't see reason why we need to support that or explicitly call it out as unsupported. But leaving this comment just in case it sparks something in someone else.

[bmorelli25]

If the newest version is first, wouldn't that make the order the reverse of product development progression?

For example, what I'm seeing currently in docs-content is a lot of stack: preview 9.0, ga 9.1. This is oldest version first and therefore the order of product development progression.

Whatever we decide upon, we should add an example.

[bmorelli25]

In best-practices.md you talk about keys needing to be in the same order for consistency. Should this file be the source of truth on what that order is?

[colleenmcginnis]

Good idea.

[bmorelli25]

Isn't this guidance in conflict with earlier guidance:

Tabs

In the future (elastic/docs-builder#1436), tabs will be able to accept applies_to information. Until then, if an applies_to badge is relevant to the entire tab item, add the badge to the beginning of the content.

I think what you're suggesting here is that the tabs should be labeled with the relevant version number or deployment method?

Then again, that's probably what we have to do until #1436 lands.

[bmorelli25]

Could use Logstash Plugin Ref?

[bmorelli25]

I like this idea. Can hide previous lifecycle state docs as a new lifecycle comes out (preview --> beta --> ga)

[bmorelli25]

Suggested change

	## Screenshots vary [screenshot]
	### Solution A: Use tabs [screenshot-tabs]
	**When to use tabs**:
	**Best practices**:
	**Example**:
	### Solution B: Add a note [screenshot-note]
	**When to use a note**:
	**Best practices**:
	**Example**:
	## Screenshots vary [screenshot]
	Sometimes the UI differs between versions, deployment types (Stack vs. Serverless), or other conditions.
	### Solution A: Use tabs [screenshot-tabs]
	**When to use tabs**:
	* When the screenshot shows significantly different interfaces or workflows for each product, deployment type, or version.
	* When the screenshot represents a specific, interactive action, like clicking a button or navigating a UI that changes meaningfully between contexts.
	**Best practices**:
	* Keep any explanatory text outside the tab unless it's specific to the screenshot inside.
	**Example**:
	A walkthrough for configuring alerts in Kibana differs between Elastic Stack and Serverless deployments.
	### Solution B: Add a note [screenshot-note]
	In cases where only a small visual detail differs (e.g., a button label or icon), it’s often more efficient to add a note rather than creating tabbed screenshots.
	**When to use a note**:
	* When the screenshot is mostly consistent, but includes minor visual or behavioral differences.
	* When adding another screenshot would be redundant or distracting.
	**Best practices**:
	* Keep notes concise, ideally one sentence.
	* Place the note directly after the screenshot.
	* Use an `applies_to` badge at the start of the note if relevant.
	**Example**:
	In Serverless, the "Create rule" button is labeled "Add rule."

[bmorelli25]

Maybe?

Suggested change

	### Solution B: Use tabs [multiple-block-tabs]
	**When to use tabs**:
	**Best practices**:
	### Solution B: Use tabs [multiple-block-tabs]
	**When to use tabs**:
	* When the content is structurally similar but differs in detail — for example, slightly different instructions, outputs, or paths.
	* When you want to avoid repeating most of the surrounding content and isolate just the difference.
	**Best practices**:
	- Only include content that varies inside the tab — don’t wrap entire pages or unrelated information.
	- Keep tabs short and focused to reduce cognitive load.
	- Label tabs clearly and consistently (e.g., by version or product).