# Troubleshooting pages

## Purpose

A troubleshooting page fixes a symptom the reader is looking at right now. It applies the [how-to](/en/documentation/style-guide/content/how-to-guides/) 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](/en/documentation/style-guide/content/how-to-guides/).
- Do not write one when the product works as designed. The reasons behind a design belong in a [concept](/en/documentation/style-guide/content/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](/en/documentation/style-guide/writing/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>`:

```mdx
import FrameBox from '@aziontech/webkit/frame-box'
import ItemList from '@aziontech/webkit/item-list'
import DocItem from '@aziontech/webkit/doc-item'

[One scope sentence: the product and the class of
symptoms the page covers.]

---

## <Observable behavior, with the error string as plain text>

<The symptom: what the reader sees, in one or two sentences.>

<The cause.>

To <fix the symptom>:

1. <One imperative instruction.>
2. <One imperative instruction.>

<The outcome the reader should now see.>

---

## <Next symptom, readable alone>

<The symptom.>

<The cause.>

- **<Remedy name>**: <what it does and its link>.

<The outcome.>

---

## Related resources

<FrameBox>
<ItemList>
  <DocItem title="<Title>" href="/path/"><the how-to or reference page the fixes lean on></DocItem>
</ItemList>
</FrameBox>
```

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](/en/documentation/style-guide/writing/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:

```mdx
**Web Application Firewall (WAF)** can block legitimate requests when an internal rule matches them. This page covers these false positives and the allowed rules that fix them.

---

## 403 Forbidden on legitimate requests

After you turn on the WAF in blocking mode, legitimate requests receive a `403 Forbidden` response.

The cause is a WAF internal rule that matches the request. Common examples include:

| Rule ID | Matches |
| --- | --- |
| `1000` | SQL keywords |
| `1013` | Apostrophe (`'`) |
| `1302` | HTML open tag (`<`) |

To find the rule and allow the legitimate requests with WAF Tuning:

1. Access [Azion Console](https://console.azion.com/) > **WAF Rules** > **your rule set**.
2. Go to the **Tuning** tab.
3. Set a **Time Range**, for example _Last 12 hours_. WAF Tuning queries cover up to 3 days.
4. In the **Workloads** dropdown, select the domains to analyze. Results only appear with at least one domain selected.
5. Select **Apply**. The **Possible Attacks** list shows **Rule ID**, **Description**, **Hits**, **Paths**, **IPs**, and **Countries**.
6. (Optional) To see more details for a record, select **More Details**.
7. Use the **Field** checkbox to select the legitimate records.
8. Select **Allow Rules**.

The new allowed rule appears in the **Allowed Rules** tab of the **WAF Rules** page. The WAF no longer blocks the requests that match the allowed rule.
```

## Related

- [How-to guides](/en/documentation/style-guide/content/how-to-guides.md): The base form this pattern applies.
- [Information architecture](/en/documentation/style-guide/content/information-architecture.md): Where platform-wide and product-specific troubleshooting live.
- [Choose a content type](/en/documentation/style-guide/content/choose-a-content-type.md): The full catalogue of page kinds.