Troubleshooting pages

Purpose

A troubleshooting page fixes a symptom the reader is looking at right now. It applies the how-to base form: the task is a fix.

When to use

• Write a troubleshooting page when a known failure has a fix the reader can apply alone.
• Write one page for a group of related symptoms, with one section per symptom.
• Do not write a troubleshooting page for a task the reader plans. A planned task needs a how-to guide.
• Do not write one when the product works as designed. The reasons behind a design belong in a concept page.
• Do not write one when the only fix is a support ticket. A page whose only step is “open a ticket” is a link, not a page.

Register

Procedural: 20 words per sentence, one instruction per step, imperative and active. Tone: calm, plain, directive, remedial. Sentence structure holds the rules.

Structure

The title is shaped Troubleshoot <feature or symptom class>: Troubleshoot WAF blocking legitimate requests.

Required components

• Opening move: one scope sentence naming the product and the class of symptoms the page covers.
• Symptom sections: one ## per symptom, each fully self-contained and readable in any order.
• Symptom headings: a noun phrase stating the observable behavior, quoting the error string verbatim as plain text: ## 403 Forbidden on legitimate requests. No inline code in a heading: backticks render a code chip that breaks the heading line.
• The symptom: what the reader sees, in one or two sentences, first in every section.
• The cause: what produces the symptom.
• The fix: a numbered procedure, or remedy bullets shaped **<Remedy name>**: what it does and its link.
• The outcome: what the reader should now see, closing every section.
• Related resources: a closing ## Related resources section, a DocItem list of the how-to and reference pages the fixes lean on.

Optional components

• Error output: the message or the screen that confirms the reader has this symptom.
• Support escalation: one aside linking the support path, placed after every fix.

Template

Copy the template and replace each <placeholder>:

Separate the symptom sections with a --- rule, and never place one directly after the frontmatter.

Rules

• Name the page after the symptom class. The title is shaped Troubleshoot <feature or symptom class>.
• Open with one scope sentence naming the product and the class of symptoms the page covers.
• Name the symptom, not the cause. The reader searches with what they see. Quote error strings verbatim: in body text in monospace, in a heading as plain text, because backticks render a code chip that breaks the heading line.
• Make each symptom section stand alone. The reader arrives at any section first; name the subject in each one.
• Keep the order inside each section: the symptom, the cause, the fix, the outcome.
• Order causes by frequency. When a symptom has more than one cause, the reader tries fixes top-down.
• Write fixes as numbered imperative steps per Procedures, or as remedy bullets shaped **<Remedy name>**: what it does and its link.
• Link long procedures instead of restating them. The fix section holds what is specific to the symptom; the generic path is a link.
• Close with ## Related resources: a DocItem list of the how-to and reference pages the fixes lean on. A support-escalation aside may come before it.
• Place by scope. Platform-wide problems in Support, product problems in that product’s guides.

Examples

This excerpt of a troubleshooting page for WAF false positives shows the opening move and the first symptom section:

Related