Add troubleshooting content type guidelines

contribute-docs/content-types/_snippets/templates/troubleshooting-template.md

@@ -0,0 +1,138 @@
+---
+navigation_title: "[Short title that works in the context of existing navigation folders]"
+description: "[Describe the user-visible problem this page helps resolve, suitable for search results and tooltips]."
+type: troubleshooting
+applies_to:
+  stack:
+  serverless:
+products:
+  - id:
+---
+
+<!--
+Copy and paste this template to get started writing your troubleshooting page, deleting the instructions and comments from your final page.
+
+For complete guidance, refer to [the troubleshooting guide](https://www.elastic.co/docs/contribute-docs/content-types/troubleshooting).
+-->
+
+# [Problem statement written from the user’s perspective]
+
+<!-- REQUIRED
+
+Describe the problem users are experiencing.
+
+Example: EDOT Collector doesn't propagate client metadata
+-->
+
+<!-- REQUIRED
+
+Introduction
+
+A brief summary of what the page helps users resolve. Keep it concise and focused on the problem, not the solution. Help users quickly confirm they're in the right place by describing the issue they're experiencing.
+-->
+
+## Symptoms
+
+<!-- REQUIRED
+
+Describe what users observe when the problem occurs. Focus on the symptoms themselves, not their causes. Use bullet points. If applicable, include:
+
+- Error messages
+- Log output
+- Missing or unexpected behavior
+- Timeouts or performance issues
+-->
+
+## Diagnosis
+
+<!-- OPTIONAL
+
+Use a Diagnosis section when you need to help users narrow down the problem from an initial symptom before providing the resolution. This is especially useful when:
+
+- The initial symptom requires diagnostic steps to identify the specific cause
+- Multiple resolutions depend on diagnostic findings
+- The same symptom can have multiple root causes
+
+Use numbered steps or bullet points to guide users through the diagnostic process.
+-->
+
+## Resolution
+
+<!-- REQUIRED
+
+Provide clear, actionable steps to resolve the issue.
+
+- Order steps from most common to least common to resolve the issue
+- Numbered instructions that begin with imperative verb phrases
+- Keep each step focused on a single action
+- Use the stepper component
+- Avoid diagnostic branching unless the problem cannot be resolved linearly.
+
+For complex scenarios, consider these patterns:
+
+- Multiple resolutions or "combo" resolutions: When multiple solutions can be applied together or independently, present them as a list of options (users can choose one or combine multiple approaches).
+
+- Resolutions that differ by deployment type: When steps differ significantly by deployment type ({{ecloud}} versus self-managed versus ECK), organize by deployment type using clear headings.
+
+- Separating diagnosis from causes and resolution: When multiple resolutions depend on diagnostic findings, use a separate Diagnosis section before Resolution to help users identify their specific situation first.
+
+For more information about the stepper component, refer to [the syntax guide](https://elastic.github.io/docs-builder/syntax/stepper/).
+-->
+
+```markdown
+:::::{stepper}
+
+::::{step} [Step title]
+[Step description or instruction - begin with an imperative verb]
+::::
+
+::::{step} [Step title]
+[Step description or instruction - begin with an imperative verb]
+::::
+
+::::{step} [Step title]
+[Step description or instruction - begin with an imperative verb]
+::::
+
+:::::
+```
+
+## Best practices
+
+<!-- OPTIONAL BUT RECOMMENDED 
+
+Explain how to avoid this issue in the future. Use bullet points. Do not restate general product best practices or guidance that applies broadly beyond this issue.
+-->
+
+## Resources
+
+<!-- OPTIONAL 
+
+Link to related documentation for deeper context. These links are supplementary — all information required to fix the issue should already be on this page.
+
+Avoid linking to GitHub issues, pull requests, or internal discussions. Resources should be stable, user-facing documentation.
+-->
+
+- [Related documentation link]
+- [Contrib/upstream reference]
+
+## Contact support
+
+<!-- OPTIONAL
+
+Use this section only if there is no dedicated "Contact support" page available in the troubleshooting folder.
+-->
+
+## Contact us
+
+If you have an [Elastic subscription](https://www.elastic.co/pricing), then you can contact Elastic support for assistance. You can reach us in the following ways:
+
+* Through the [Elastic Support Portal](https://support.elastic.co/home). The Elastic Support Portal is the central place where you can access all of your cases, subscriptions, and licenses. Within a few hours after subscribing, you receive an email with instructions on how to log in to the Support Portal, where you can track both current and archived cases.
+
+  You can access the portal [directly](https://support.elastic.co/home), or by clicking on the life preserver icon on any page in {{ecloud}}.
+
+* By email: [email protected]
+
+:::{tip}
+If you contact us by email, use the email address that you registered with so that we can help you more quickly. If you are using a distribution list as your registered email, you can also register a second email address with us. Just open a case to let us know the name and email address you want to add.
+:::

contribute-docs/content-types/index.md

@@ -1,6 +1,9 @@
 ---
 navigation_title: "Content types"
 description: "Overview of guidelines for choosing the appropriate content types in the Elastic documentation."
+applies_to:
+  stack: 
+  serverless: 
 ---
 
 # Elastic Docs content types
@@ -44,6 +47,7 @@ A tutorial should always be a standalone page, meaning it should have only one c
 
 - [How-to guides](how-tos.md)
 - [Overviews](overviews.md)
+- [Troubleshooting](troubleshooting.md)
 % - [Tutorial](tutorials.md)
 
 ## Templates per content type

contribute-docs/content-types/troubleshooting.md

@@ -0,0 +1,115 @@
+---
+navigation_title: "Troubleshooting"
+description: "Guidance for writing troubleshooting content that help users diagnose and resolve specific problems quickly and effectively."
+applies_to:
+  stack: 
+  serverless: 
+---
+
+# Troubleshooting
+
+This page provides guidelines for Elastic Docs contributors on how to write effective troubleshooting pages in the Elastic docs.
+
+## Types of troubleshooting content
+
+There are several subtypes of troubleshooting content:
+
+* **A dedicated troubleshooting page** (preferred): Use for specific, well-defined problems. The problem appears in the page title. Includes required **Symptoms** and **Resolution** sections. Optimized for search and direct linking.
+
+* **Generic "Troubleshooting" or "Common problems" index page**: Use to organize multiple related troubleshooting topics. The title is generic (for example, "Common problems with {{product.apm}}"). Contains anchor links to sections on the same page or links to dedicated troubleshooting pages. Consider breaking out individual problems into dedicated pages as content grows.
+
+* **Troubleshooting section within a general documentation page**: Use sparingly for brief, contextual troubleshooting tied to a specific feature or quickstart. If content grows beyond a few bullet points, extract it into a dedicated troubleshooting page and link to it.
+
+The rest of this guide focuses on dedicated troubleshooting pages. Generic index pages and troubleshooting sections within general docs have different structure requirements and may not include all elements described here.
+
+## What is a troubleshooting page
+
+Troubleshooting pages help users fix specific problems they encounter while using Elastic products. They are intentionally narrow in scope (one primary issue per page), problem-driven, and focused on unblocking users as quickly as possible. 
+
+Use the troubleshooting content type when:
+
+- Users encounter a specific, repeatable problem.
+- The problem can be identified through common symptoms.
+- There is a known resolution or recommended workaround.
+
+A page that doesn't describe a specific problem isn't troubleshooting content.
+
+Readers of troubleshooting content are typically blocked or frustrated and want a fast, reliable fix. They expect clear guidance and strong recommendations without requiring background information or deep explanations. Keep troubleshooting pages short and to the point. Optimize for quick resolution, not exhaustive coverage.
+
+## Structure of a troubleshooting page
+
+To help users quickly identify and resolve problems, troubleshooting pages use a consistent structure. A predictable format helps users confirm they're in the right place and move directly to the solution they need.
+
+### Required elements
+
+The following elements are required in troubleshooting pages:
+
+1. A consistent **filename:** Succinctly describe the problem. 
+   - For example: `no-data-in-kibana.md`, `traces-dropped.md`.
+2. Appropriate **[frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter/):**
+   - `applies_to:` [Tags](https://elastic.github.io/docs-builder/syntax/applies) for versioning/availability info per the [cumulative docs guidelines](/contribute-docs/how-to/cumulative-docs/index.md).
+   - `description`: A brief summary of the page fit for search results and tooltips.
+   - `product`: The relevant Elastic product(s) the page relates to.
+3. A clear **title:** A brief description of the problem, written from the user's perspective.
+   - For example: "EDOT Collector doesn't propagate client metadata", "No application-level telemetry visible in {{kib}}", or "Logs are missing after upgrading {{agent}}".
+4. A **Symptoms** section: Describe what users can observe when the problem occurs.
+   - Focus only on user-visible behavior.
+   - Do not explain causes.
+   - Use bullet points.
+   - Include error messages, log output, or UI behavior when helpful:
+     - If the problem manifests as a specific error message, include the exact error text (or common variations) in the symptoms. Error messages are often how users identify and search for troubleshooting content.
+     - If the problem manifests as undesirable behavior without a specific error, clearly describe the observable symptoms (for example, "No data appears in {{kib}}" or "Service status shows as unhealthy").
+5. A **Resolution** section: Provide clear, actionable steps to resolve the issue. Each step should move the reader closer to a working system or help rule out possible causes or assumptions.
+   - Use numbered steps.
+   - Be prescriptive and opinionated.
+   - Include minimal configuration examples when relevant.
+   - Assume the reader's situation matches the **Symptoms** section.
+   - Avoid speculative or diagnostic language.
+   - Order steps from most common to least common to resolve the issue.
+   - Avoid diagnostic branching unless the problem cannot be resolved linearly.
+
+   For more complex scenarios, consider the following patterns:
+
+   - **Multiple resolutions or "combo" resolutions**: When multiple solutions can be applied together or independently, present them as a list of options. Users can choose one or combine multiple approaches based on their situation. For example, reducing JVM memory pressure might involve reducing shard count, avoiding expensive searches, and preventing mapping explosions, all of which can be applied together.
+
+   - **Introducing a diagnostic section**: When the initial symptom requires diagnostic steps to identify the specific cause, consider splitting the diagnostic process from the resolution. Use a separate **Diagnosis** section before the **Resolution** section to help users narrow down the problem first. This is especially useful when the same symptom can have multiple root causes or there are multiple possible resolutions that depend on diagnostic findings.
+
+   - **Resolutions that differ by deployment type**: When the resolution steps differ significantly based on deployment type (for example, {{ecloud}} versus self-managed versus ECK), organize the resolution by deployment type using clear headings or tabs. This helps users quickly find the steps relevant to their environment.
+
+### Optional elements
+
+Consider including the following when they add value:
+
+- A **Best practices** section: Use this section to explain how users can avoid encountering this specific problem again. Focus on preventive measures, configuration choices, or deployment patterns that directly relate to preventing this issue. This is the appropriate place to recommend supported or preferred patterns related to the problem, clarify Elastic-specific guidance, call out known limitations or constraints, and set expectations about scale, load, or deployment environments.
+- A **Resources** section: Provide links to supplementary documentation for readers who want deeper context. Resources must not be required to fix the issue. Prefer Elastic-owned documentation, but link to upstream or external docs when necessary.
+- A **Contact support** section: Use this section only if there is no dedicated "Contact support" page available in the troubleshooting folder.
+
+## Best practices
+
+When you create troubleshooting pages, follow these best practices:
+
+- Describe one primary issue per page.
+- Be explicit about supported and unsupported setups.
+- Optimize for fast resolution, not exhaustive coverage.
+
+## Common anti-patterns
+
+Do not use troubleshooting for teaching users how to use a feature for the first time (use a tutorial), explaining how a system works (use an overview), listing configuration options or APIs (use reference documentation), or describing general best practices that aren't tied to resolving a specific problem or preventing it from happening again.
+
+Additional common anti-patterns to avoid:
+
+- Page titles "Troubleshooting X" with no specific problem (acceptable only for index/landing pages that organize multiple troubleshooting topics)
+- Long explanations before the resolution
+- Mixing multiple unrelated issues
+
+## Template
+
+All new troubleshooting pages must be created using [the template](https://github.com/elastic/docs-content/blob/main/contribute-docs/content-types/_snippets/templates/troubleshooting-template.md).
+
+## Examples
+
+Here are some examples of well-structured troubleshooting pages in the Elastic documentation:
+
+- [No logs, metrics, or traces visible in {{kib}}](/troubleshoot/ingest/opentelemetry/no-data-in-kibana.md): Addresses a specific data visibility issue with clear symptoms and resolution steps.
+- [EDOT Collector doesn't propagate client metadata](/troubleshoot/ingest/opentelemetry/edot-collector/metadata.md): Focuses on a specific configuration problem with symptoms and actionable resolution steps.
+- [Troubleshoot common errors in {{es}}](/troubleshoot/elasticsearch/errors.md): An example of an error reference index page that organizes multiple error-based troubleshooting topics.

contribute-docs/toc.yml

@@ -8,6 +8,7 @@ toc:
       - file: index.md
       - file: how-tos.md
       - file: overviews.md
+      - file: troubleshooting.md
       - file: tutorials.md
   - folder: how-to
     children: