diff --git a/contribute-docs/content-types/_snippets/templates/troubleshooting-template.md b/contribute-docs/content-types/_snippets/templates/troubleshooting-template.md new file mode 100644 index 0000000000..945ecf5df2 --- /dev/null +++ b/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: +--- + + + +# [Problem statement written from the user’s perspective] + + + + + +## Symptoms + + + +## Diagnosis + + + +## Resolution + + + +```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 + + + +## Resources + + + +- [Related documentation link] +- [Contrib/upstream reference] + +## Contact support + + + +## 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: support@elastic.co + +:::{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. +::: \ No newline at end of file diff --git a/contribute-docs/content-types/index.md b/contribute-docs/content-types/index.md index dcc8d3245c..da8b670589 100644 --- a/contribute-docs/content-types/index.md +++ b/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 diff --git a/contribute-docs/content-types/troubleshooting.md b/contribute-docs/content-types/troubleshooting.md new file mode 100644 index 0000000000..d669d8bfda --- /dev/null +++ b/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. \ No newline at end of file diff --git a/contribute-docs/toc.yml b/contribute-docs/toc.yml index c41c16f929..9a82530939 100644 --- a/contribute-docs/toc.yml +++ b/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: