# Páginas de troubleshooting

## Propósito

Uma página de troubleshooting corrige um sintoma que o leitor está vendo agora. Ela aplica a forma base de [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/): a tarefa é uma correção.

## Quando usar

- Escreva uma página de troubleshooting quando uma falha conhecida tem uma correção que o leitor aplica sozinho.
- Escreva uma página para um grupo de sintomas relacionados, com uma seção por sintoma.
- Não escreva uma página de troubleshooting para uma tarefa que o leitor planeja. Uma tarefa planejada precisa de um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/).
- Não escreva uma página quando o produto funciona como projetado. As razões de um design pertencem a uma página de [conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/).
- Não escreva uma página quando a única correção é um ticket de suporte. Uma página cujo único passo é "abra um ticket" é um link, não uma página.

## Registro

Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo. Tom: calmo, claro, diretivo, resolutivo. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras.

## Estrutura

O título tem a forma `Troubleshoot <recurso ou classe de sintomas>` em inglês e `Solução de problemas de <recurso ou classe de sintomas>` em português.

**Componentes obrigatórios**

- **Abertura**: uma frase de escopo que nomeia o produto e a classe de sintomas que a página cobre.
- **Seções de sintoma**: uma seção `##` por sintoma, cada uma autossuficiente e legível em qualquer ordem.
- **Headings de sintoma**: uma frase nominal que declara o comportamento observável, com a mensagem de erro citada literalmente como texto simples: `## 403 Forbidden em requisições legítimas`. Sem código inline em heading: as crases renderizam um chip de código que quebra a linha do heading.
- **O sintoma**: o que o leitor vê, em uma ou duas frases, primeiro em cada seção.
- **A causa**: o que produz o sintoma.
- **A correção**: um procedimento numerado, ou marcadores na forma `**<Nome da solução>**: o que ela faz e seu link`.
- **O resultado**: o que o leitor deve ver agora, fechando cada seção.
- **Recursos relacionados**: um fechamento `## Recursos relacionados`, uma lista de `DocItem` com os guias how-to e as páginas de referência em que as correções se apoiam.

**Componentes opcionais**

- **Saída de erro**: a mensagem ou a tela que confirma que o leitor tem esse sintoma.
- **Contato com o suporte**: um aside que aponta o caminho do suporte, depois de todas as correções.

## Template

Copie o template e substitua cada `<placeholder>`:

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

[Uma frase de escopo: o produto e a classe de sintomas
que a página cobre.]

---

## <Comportamento observável, com a mensagem de erro em texto simples>

<O sintoma: o que o leitor vê, em uma ou duas frases.>

<A causa.>

Para <corrigir o sintoma>:

1. <Uma instrução imperativa.>
2. <Uma instrução imperativa.>

<O resultado que o leitor deve ver agora.>

---

## <Próximo sintoma, legível sozinho>

<O sintoma.>

<A causa.>

- **<Nome da solução>**: <o que ela faz e seu link>.

<O resultado.>

---

## Recursos relacionados

<FrameBox>
<ItemList>
  <DocItem title="<Título>" href="/caminho/"><o guia how-to ou a página de referência em que as correções se apoiam></DocItem>
</ItemList>
</FrameBox>
```

Separe as seções de sintoma com uma linha `---` e nunca coloque uma imediatamente depois do bloco de frontmatter.

## Regras

- **Nomeie a página pela classe de sintomas.** O título tem a forma `Troubleshoot <recurso ou classe de sintomas>`.
- **Abra com uma frase de escopo** que nomeia o produto e a classe de sintomas que a página cobre.
- **Nomeie o sintoma, não a causa.** O leitor busca com o que ele vê. Cite as mensagens de erro literalmente: no corpo em monospace, em um heading como texto simples, porque as crases renderizam um chip de código que quebra a linha do heading.
- **Faça cada seção de sintoma ficar de pé sozinha.** O leitor chega a qualquer seção primeiro; nomeie o assunto em cada uma.
- **Mantenha a ordem dentro de cada seção**: o sintoma, a causa, a correção, o resultado.
- **Ordene as causas por frequência.** Quando um sintoma tem mais de uma causa, o leitor tenta as correções de cima para baixo.
- **Escreva as correções como passos numerados e imperativos** conforme [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/), ou como marcadores na forma `**<Nome da solução>**: o que ela faz e seu link`.
- **Aponte procedimentos longos em vez de repeti-los.** A correção contém o que é específico do sintoma; o caminho genérico é um link.
- **Feche com `## Recursos relacionados`**: uma lista de `DocItem` com os guias how-to e as páginas de referência em que as correções se apoiam. Um aside de suporte pode vir antes.
- **Posicione pelo escopo.** Problemas da plataforma em Suporte, problemas de produto nos guias daquele produto.

## Exemplos

Este exemplo, em inglês, mostra a abertura e a primeira seção de sintoma de uma página de troubleshooting sobre falsos positivos do WAF:

```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.
```

## Relacionados

- [Guias how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to.md): A forma base que este padrão aplica.
- [Arquitetura de informação](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao.md): Onde vivem o troubleshooting da plataforma e o de produto.
- [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo.md): O catálogo completo de tipos de página.