# Páginas de conceito

## Propósito

Uma página de conceito constrói entendimento. O leitor não está no meio de uma tarefa; ele quer entender como algo funciona e por que é construído assim, normalmente antes de decidir usar.

Ela aplica a forma base de **explicação**, uma das quatro formas do Diátaxis. Quando produtos e recursos da plataforma se combinam em uma arquitetura de referência, escreva uma [página de arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura/): é a mesma forma base, com diagrama e dataflow.

## Quando usar

Escreva uma página de conceito quando:

- O leitor quer a razão de o produto funcionar assim, e não os passos.
- Um guia how-to ganha um preâmbulo longo, ou uma página de referência para para justificar um design.
- A página precisa comparar alternativas e nomear um trade-off.

Não escreva uma página de conceito quando:

- O leitor precisa consultar um valor, um campo ou um limite. Escreva uma [página de referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/).
- O leitor precisa de passos para uma tarefa. Escreva um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) ou um [tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/).
- O assunto é como produtos e recursos da plataforma se combinam em uma arquitetura de referência. Escreva uma [página de arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura/).

Este é o tipo de página que mais falta. Quando outro tipo começa a explicar, escreva a página de conceito e mantenha aquele tipo limpo.

## Registro

Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é genuinamente desconhecido ou é a própria plataforma. Tom: explicativo, descritivo, equilibrado, paciente. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras.

## Estrutura

O título é `Como <X> funciona`, `Sobre <X>` ou uma frase nominal curta: `Como o Tiered Cache funciona`.

**Componentes obrigatórios**

- **Abertura**: uma declaração de como o sistema se comporta, nos termos do leitor antes de nomear qualquer objeto da Azion. Nunca `Esta página explica`.
- **Frase-roteiro**: a introdução termina com uma frase que nomeia os mecanismos que as seções `##` cobrem, na ordem.
- **Seções de mecanismo**: uma seção `##` em frase nominal por mecanismo, espelhando a frase-roteiro.
- **O problema, o mecanismo e o trade-off**: cada seção cobre os três. Uma explicação que apresenta só vantagens é marketing.
- **Recursos relacionados**: um fechamento `## Recursos relacionados`, uma lista de `DocItem` com a página de referência e os guias how-to que aplicam o conceito, cada linha com seu motivo.

**Componentes opcionais**

- **Termos principais**: o vocabulário que o leitor precisa, definido uma vez cada.
- **Alternativas**: as outras formas de resolver o problema, e o que cada uma abre mão.
- **Um diagrama**: quando a relação é mais fácil de desenhar do que de descrever. Desenhe como um bloco de código `mermaid`, e rotule cada nó com palavras.

## 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 declaração de como o sistema se comporta.>
<Uma frase-roteiro que nomeia os mecanismos que as
seções cobrem, na ordem.>

## <Frase nominal que nomeia o primeiro mecanismo>

<O problema contra o qual este mecanismo trabalha, como
ele se comporta e o que ele custa.>

## <Frase nominal que nomeia o próximo mecanismo>

<...>

## Recursos relacionados

<FrameBox>
<ItemList>
  <DocItem title="<A página de referência>" href="/caminho/"><o que o leitor encontra lá></DocItem>
  <DocItem title="<O guia how-to que aplica o conceito>" href="/caminho/"><por que o leitor seguiria o link></DocItem>
</ItemList>
</FrameBox>
```

## Regras

- **Abra com comportamento, não com moldura.** Declare como o sistema se comporta; nunca `Esta página explica`.
- **Explique a coisa antes do objeto da Azion.** `Cache stores a copy of a response in the data center that fetched it. That data center answers later requests for the same object from that copy, without reaching the origin.` Só depois os objetos que a realizam. Uma abertura em que todo sujeito é um produto ou objeto da Azion é um inventário, não uma explicação.
- **Espelhe a frase-roteiro.** Uma seção `##` em frase nominal por mecanismo, na ordem em que a frase-roteiro os nomeia. Uma seção cortada da página é cortada da frase-roteiro na mesma edição.
- **Declare o trade-off.** Toda escolha de design custa algo, então diga o quê. Uma explicação que apresenta só vantagens é marketing.
- **Sem procedimentos.** Aponte o [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) que aplica o conceito.
- **Mantenha as alternativas aqui.** Alternativas e "em vez de" vivem nas páginas de conceito e em nenhum outro lugar.
- **Use a voz passiva de forma restrita.** Apenas quando o agente é genuinamente desconhecido ou é a própria plataforma.
- **Faça os diagramas carregarem significado, e desenhe em `mermaid`.** Um diagrama em texto alcança um agente que lê o gêmeo em markdown; uma imagem não. Diga em prosa o que o diagrama mostra, e nunca dependa apenas de cor.
- **Discuta, não enumere.** Uma página que vira tabela de campos quer ser [referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/).
- **Defina cada termo uma vez**, onde o leitor o encontra primeiro, e depois aponte para ele.
- **Evite afirmações que expiram.** `Atualmente` e `em breve` envelhecem mal e ninguém volta.

## Exemplos

Este exemplo, em inglês, mostra a abertura, a frase-roteiro e a primeira seção de mecanismo de uma página de conceito sobre o Tiered Cache:

```mdx
**Tiered Cache** is a Cache feature that adds a cache layer between Azion's distributed infrastructure and the origin servers. With Tiered Cache enabled for the application, content stays cached for longer periods and the origin receives fewer requests. Tiered Cache is designed for objects that can remain in cache for a long period of time. Tiered Cache is available on request: activation goes through the Sales team.

Its behavior depends on five mechanisms: the cache layers, the second-layer region, the TTL requirements, the Bypass Cache limitation, and the purge order.

## Cache layers

End users send requests to Azion's distributed infrastructure, where content is cached. Without Tiered Cache, a request that misses the first cache layer goes to the origin. Tiered Cache adds a second cache layer between that first layer and the origin servers. The tiered layer can answer a request that misses the first layer, so the request does not reach the origin. Content stays cached for longer periods, and the origin receives fewer requests.
```

## Relacionados

- [Páginas de arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura.md): A mesma forma base, para um design que atravessa produtos.
- [Referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia.md): Onde as configurações e os limites pertencem.
- [Guias how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to.md): Onde os passos pertencem.
- [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.