Skip to content

Commit 0e77e5f

Browse files
alexandra5000alexandra5000
authored
Add troubleshooting content type guidelines (#4512)
This PR introduces a new "Troubleshooting" content type with detailed guidelines for creating effective troubleshooting pages in the Elastic documentation. Additionally, a template for troubleshooting pages is added. Updates to the content types `index.md` file are also made to include the new troubleshooting section.
1 parent b79f5fe commit 0e77e5f

File tree

4 files changed

+258
-0
lines changed

4 files changed

+258
-0
lines changed

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

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
navigation_title: "[Short title that works in the context of existing navigation folders]"
3+
description: "[Describe the user-visible problem this page helps resolve, suitable for search results and tooltips]."
4+
type: troubleshooting
5+
applies_to:
6+
stack:
7+
serverless:
8+
products:
9+
- id:
10+
---
11+
12+
<!--
13+
Copy and paste this template to get started writing your troubleshooting page, deleting the instructions and comments from your final page.
14+
15+
For complete guidance, refer to [the troubleshooting guide](https://www.elastic.co/docs/contribute-docs/content-types/troubleshooting).
16+
-->
17+
18+
# [Problem statement written from the user’s perspective]
19+
20+
<!-- REQUIRED
21+
22+
Describe the problem users are experiencing.
23+
24+
Example: EDOT Collector doesn't propagate client metadata
25+
-->
26+
27+
<!-- REQUIRED
28+
29+
Introduction
30+
31+
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.
32+
-->
33+
34+
## Symptoms
35+
36+
<!-- REQUIRED
37+
38+
Describe what users observe when the problem occurs. Focus on the symptoms themselves, not their causes. Use bullet points. If applicable, include:
39+
40+
- Error messages
41+
- Log output
42+
- Missing or unexpected behavior
43+
- Timeouts or performance issues
44+
-->
45+
46+
## Diagnosis
47+
48+
<!-- OPTIONAL
49+
50+
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:
51+
52+
- The initial symptom requires diagnostic steps to identify the specific cause
53+
- Multiple resolutions depend on diagnostic findings
54+
- The same symptom can have multiple root causes
55+
56+
Use numbered steps or bullet points to guide users through the diagnostic process.
57+
-->
58+
59+
## Resolution
60+
61+
<!-- REQUIRED
62+
63+
Provide clear, actionable steps to resolve the issue.
64+
65+
- Order steps from most common to least common to resolve the issue
66+
- Numbered instructions that begin with imperative verb phrases
67+
- Keep each step focused on a single action
68+
- Use the stepper component
69+
- Avoid diagnostic branching unless the problem cannot be resolved linearly.
70+
71+
For complex scenarios, consider these patterns:
72+
73+
- 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).
74+
75+
- 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.
76+
77+
- 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.
78+
79+
For more information about the stepper component, refer to [the syntax guide](https://elastic.github.io/docs-builder/syntax/stepper/).
80+
-->
81+
82+
```markdown
83+
:::::{stepper}
84+
85+
::::{step} [Step title]
86+
[Step description or instruction - begin with an imperative verb]
87+
::::
88+
89+
::::{step} [Step title]
90+
[Step description or instruction - begin with an imperative verb]
91+
::::
92+
93+
::::{step} [Step title]
94+
[Step description or instruction - begin with an imperative verb]
95+
::::
96+
97+
:::::
98+
```
99+
100+
## Best practices
101+
102+
<!-- OPTIONAL BUT RECOMMENDED
103+
104+
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.
105+
-->
106+
107+
## Resources
108+
109+
<!-- OPTIONAL
110+
111+
Link to related documentation for deeper context. These links are supplementary — all information required to fix the issue should already be on this page.
112+
113+
Avoid linking to GitHub issues, pull requests, or internal discussions. Resources should be stable, user-facing documentation.
114+
-->
115+
116+
- [Related documentation link]
117+
- [Contrib/upstream reference]
118+
119+
## Contact support
120+
121+
<!-- OPTIONAL
122+
123+
Use this section only if there is no dedicated "Contact support" page available in the troubleshooting folder.
124+
-->
125+
126+
## Contact us
127+
128+
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:
129+
130+
* 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.
131+
132+
You can access the portal [directly](https://support.elastic.co/home), or by clicking on the life preserver icon on any page in {{ecloud}}.
133+
134+
* By email: support@elastic.co
135+
136+
:::{tip}
137+
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.
138+
:::

‎contribute-docs/content-types/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
---
22
navigation_title: "Content types"
33
description: "Overview of guidelines for choosing the appropriate content types in the Elastic documentation."
4+
applies_to:
5+
stack:
6+
serverless:
47
---
58

69
# Elastic Docs content types
@@ -44,6 +47,7 @@ A tutorial should always be a standalone page, meaning it should have only one c
4447

4548
- [How-to guides](how-tos.md)
4649
- [Overviews](overviews.md)
50+
- [Troubleshooting](troubleshooting.md)
4751
% - [Tutorial](tutorials.md)
4852

4953
## Templates per content type

‎contribute-docs/content-types/troubleshooting.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
navigation_title: "Troubleshooting"
3+
description: "Guidance for writing troubleshooting content that help users diagnose and resolve specific problems quickly and effectively."
4+
applies_to:
5+
stack:
6+
serverless:
7+
---
8+
9+
# Troubleshooting
10+
11+
This page provides guidelines for Elastic Docs contributors on how to write effective troubleshooting pages in the Elastic docs.
12+
13+
## Types of troubleshooting content
14+
15+
There are several subtypes of troubleshooting content:
16+
17+
* **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.
18+
19+
* **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.
20+
21+
* **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.
22+
23+
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.
24+
25+
## What is a troubleshooting page
26+
27+
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.
28+
29+
Use the troubleshooting content type when:
30+
31+
- Users encounter a specific, repeatable problem.
32+
- The problem can be identified through common symptoms.
33+
- There is a known resolution or recommended workaround.
34+
35+
A page that doesn't describe a specific problem isn't troubleshooting content.
36+
37+
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.
38+
39+
## Structure of a troubleshooting page
40+
41+
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.
42+
43+
### Required elements
44+
45+
The following elements are required in troubleshooting pages:
46+
47+
1. A consistent **filename:** Succinctly describe the problem.
48+
- For example: `no-data-in-kibana.md`, `traces-dropped.md`.
49+
2. Appropriate **[frontmatter](https://elastic.github.io/docs-builder/syntax/frontmatter/):**
50+
- `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).
51+
- `description`: A brief summary of the page fit for search results and tooltips.
52+
- `product`: The relevant Elastic product(s) the page relates to.
53+
3. A clear **title:** A brief description of the problem, written from the user's perspective.
54+
- For example: "EDOT Collector doesn't propagate client metadata", "No application-level telemetry visible in {{kib}}", or "Logs are missing after upgrading {{agent}}".
55+
4. A **Symptoms** section: Describe what users can observe when the problem occurs.
56+
- Focus only on user-visible behavior.
57+
- Do not explain causes.
58+
- Use bullet points.
59+
- Include error messages, log output, or UI behavior when helpful:
60+
- 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.
61+
- 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").
62+
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.
63+
- Use numbered steps.
64+
- Be prescriptive and opinionated.
65+
- Include minimal configuration examples when relevant.
66+
- Assume the reader's situation matches the **Symptoms** section.
67+
- Avoid speculative or diagnostic language.
68+
- Order steps from most common to least common to resolve the issue.
69+
- Avoid diagnostic branching unless the problem cannot be resolved linearly.
70+
71+
For more complex scenarios, consider the following patterns:
72+
73+
- **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.
74+
75+
- **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.
76+
77+
- **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.
78+
79+
### Optional elements
80+
81+
Consider including the following when they add value:
82+
83+
- 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.
84+
- 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.
85+
- A **Contact support** section: Use this section only if there is no dedicated "Contact support" page available in the troubleshooting folder.
86+
87+
## Best practices
88+
89+
When you create troubleshooting pages, follow these best practices:
90+
91+
- Describe one primary issue per page.
92+
- Be explicit about supported and unsupported setups.
93+
- Optimize for fast resolution, not exhaustive coverage.
94+
95+
## Common anti-patterns
96+
97+
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.
98+
99+
Additional common anti-patterns to avoid:
100+
101+
- Page titles "Troubleshooting X" with no specific problem (acceptable only for index/landing pages that organize multiple troubleshooting topics)
102+
- Long explanations before the resolution
103+
- Mixing multiple unrelated issues
104+
105+
## Template
106+
107+
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).
108+
109+
## Examples
110+
111+
Here are some examples of well-structured troubleshooting pages in the Elastic documentation:
112+
113+
- [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.
114+
- [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.
115+
- [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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ toc:
88
- file: index.md
99
- file: how-tos.md
1010
- file: overviews.md
11+
- file: troubleshooting.md
1112
- file: tutorials.md
1213
- folder: how-to
1314
children:

0 commit comments

Comments
 (0)