# Páginas de visão geral

## Propósito

Uma página de visão geral é a raiz da seção de um produto. Ela diz o que o produto é, o que ele faz e quando o leitor o usaria. Ela explica a classe da coisa antes de nomear a versão da Azion, para que um leitor que nunca usou uma consiga acompanhar a página. Ela aplica a forma base de [referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/).

Todo produto tem uma. É a página onde o leitor chega pela busca, pelo menu lateral e por outro produto que aponta para este.

## Quando usar

- Escreva uma visão geral para cada produto, como a primeira página da seção.
- Escreva-a antes de qualquer outra página da seção. A visão geral define do que a seção trata.

Não escreva uma visão geral quando:

- O assunto é uma funcionalidade, como Tiered Cache ou Real-Time Purge. Isso vai em uma [página de referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/) dentro da seção. Um produto aninhado em um recurso da plataforma não é uma funcionalidade e não tem página de visão geral própria: a visão geral do recurso o apresenta.
- A página levaria o leitor por uma tarefa. Isso é um [guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/), com link a partir daqui.
- A página só listaria links. Isso é um [hub de navegação](/pt-br/documentacao/guia-de-estilo/conteudo/hubs-de-navegacao/).

## Registro

Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é desconhecido. Tom: acolhedor, factual, direto. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras.

## Estrutura

**Componentes obrigatórios**

- **Bloco de definição**, em duas camadas. Primeiro o conceito: uma ou duas frases dizendo o que é a classe da coisa, para um leitor que nunca usou uma, com qualquer termo do mercado definido no próprio texto. Depois o produto: `**<Produto>** <verbo> <o conceito> <onde e como na Azion>.` Depois uma frase nomeando as tarefas concretas para as quais as pessoas o usam, no vocabulário do leitor: `Use <Produto> para fazer A, executar B ou servir C.` Uma lista de benefícios em bullets é a forma mais fraca dessa frase: parece um folheto e custa uma tela.
- **CTAs**: um `DocButton` primário com o label **Quickstart** e um secundário com o label `Referência de <Produto>`.
- **A amostra**: quando o produto tem um artefato de código, um objeto de configuração ou uma requisição, um exemplo completo e mínimo dele, inteiro, na primeira tela. Dois a quatro bullets nomeiam as partes, e uma frase diz qual conhecimento prévio se aproveita. Um produto sem esse artefato pula a seção em vez de inventar uma.
- **O mecanismo**: quando uma requisição, um evento ou um job atravessa mais de dois objetos antes de o produto executar, essa cadeia como um diagrama `mermaid`, seguido de um percurso numerado com no máximo seis itens. Abra com o que o leitor presumiria errado.
- **Os recursos**: somente em um recurso da plataforma que hospeda produtos. Para cada produto, diga o que ele faz neste recurso e quando o leitor o ativa, em uma ou duas frases, e depois aponte para onde o leitor vai para usá-lo. É o que o leitor precisa para decidir se abre o produto, nunca a lista de features.
- **As fronteiras**: um único bloco compacto de bullets com introduções em negrito — linguagens, APIs, frameworks, integrações e os principais limites. Um bloco, não uma seção por feature.
- **Seções de capacidade**: só para uma capacidade que muda o que o leitor construiria, no máximo três. Uma capacidade que cabe em uma frase e um link pertence ao bloco de fronteiras ou ao roteador.
- **Fechamento**: `## Próximos passos`, um `DocCardGroup` indexado pelo que o leitor quer fazer: cada card nomeia o destino, e seu texto é a intenção (`Executar o primeiro agora.`).

As seções mantêm essa ordem.

## Template

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

```mdx
import DocButton from '~/components/webkit/DocButton.vue'
import DocCardGroup from '@aziontech/webkit/doc-card-group'
import DocCard from '@aziontech/webkit/doc-card'

<O que é a classe da coisa, para um leitor que nunca usou uma. Uma ou duas frases; defina qualquer termo do mercado no próprio texto.>

**<Produto>** <verbo> <o conceito> <onde e como na Azion>. Use <Produto> para <tarefa A>, <tarefa B> ou <tarefa C>.

<DocButton href="<URL do quickstart>" label="Quickstart" size="medium" />
<DocButton href="<URL da referência>" label="Referência de <Produto>" kind="secondary" size="medium" />

## <O artefato, como expressão nominal>

<Um exemplo completo e mínimo do artefato.>

- **<Parte>**: <o que é>.
- **<Parte>**: <o que é>.

<Uma frase sobre qual conhecimento prévio se aproveita.>

---

## <A cadeia, como expressão nominal>

<O que o leitor presumiria errado.>

<Um fence mermaid desenhando a cadeia da requisição à resposta.>

1. <O que acontece primeiro.>
2. <...>

## <As fronteiras, como expressão nominal>

- **<Dimensão>**: <o que suporta, e onde para>.
- **<Dimensão>**: <...>.

---

## Próximos passos

<DocCardGroup cols={2}>
  <DocCard title="Quickstart" href="<url>" label="<Executar o primeiro agora>." />
  <DocCard title="Referência" href="<url>" label="<Consultar um campo, um limite ou um padrão>." />
</DocCardGroup>
```

## Regras

- **Nunca instrua.** Sem passos numerados, sem procedimentos, sem sequências de cliques. A amostra não é um walkthrough: ela aparece uma vez, completa, sem nada para o leitor fazer. Uma visão geral que instrui é uma página de [quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) arquivada no lugar errado.
- **Sem adjetivos de qualidade.** Diga o que o produto faz e onde para.
- **O título é o nome do produto, um substantivo.** Não "documentação", não um gerúndio.
- **Explique a coisa antes do produto.** A primeira frase diz o que é a classe da coisa; a frase do produto vem depois. Cubra o nome do produto: o que sobra precisa valer para a versão de qualquer fornecedor.
- **Nomeie o produto até a segunda frase, e nunca abra com o contexto do problema.** Uma frase de conceito explica um mecanismo. Uma frase sobre a importância do problema não explica nada.
- **Organize pelas perguntas do leitor, não pela sua lista de features.** As seções respondem, na ordem: o que é isto e o que a versão da Azion faz, o que eu escrevo, como isso é chamado, quais produtos ele hospeda, o que faz e onde para, para onde vou agora. Um sumário que reproduz a lista de features do produto é um catálogo: responde "o que vendemos" em vez de "o que estou decidindo".
- **As perguntas moldam as seções; elas nunca viram títulos.** Um título é uma expressão nominal curta, nunca uma pergunta: `Estrutura da function`, não `Como é uma function`.
- **Desenhe o diagrama a partir da sequência documentada.** Um diagrama de uma sequência que a documentação já descreve em prosa é uma mudança de notação, não um fato novo. Cada nó e cada seta corresponde a um passo que o produto executa, e o percurso numerado carrega o significado se a figura não renderizar.
- **Envie o leitor para o [Quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/)**, nos CTAs e de novo no roteador.
- **Nunca encurte a amostra nem tire o diagrama para deixar a página mais curta.** Eles são as duas coisas que o leitor veio buscar. Uma página que cresceu demais cresceu em seções de capacidade; comprima essas no bloco de fronteiras.

## Exemplos

Este trecho, em inglês, da visão geral de **Functions** mostra o bloco de definição em duas camadas e depois a amostra. O primeiro parágrafo explica o que é uma function para um leitor que nunca usou uma; o segundo nomeia o produto e o que ele faz na Azion; a amostra mostra o artefato em vez de descrevê-lo:

```mdx
A function is code that runs when a request arrives, on infrastructure Azion operates. You write a handler that receives the request and returns a response. The platform starts the handler on demand and stops it when the response is sent, so there is no server to provision or scale. That model is called [serverless](https://www.azion.com/en/learning/serverless/what-is-serverless/).

**Functions** runs that code in JavaScript on Azion's distributed infrastructure, inside the request path of an application or a firewall. Use Functions to build APIs, manipulate request and response headers, apply logic from request metadata, or block traffic before it reaches your application.

## Function structure

A function exports one default object whose keys are handlers. The `fetch` handler answers an HTTP request:

<Code client:visible lang="javascript" code={`
export default {
  fetch: async (request, env, ctx) => {
    return new Response('Hello World');
  }
};
`} />

- **`export default`** exposes the object Azion Runtime reads. Each key names a handler for one event.
- **`fetch(request, env, ctx)`** runs on an HTTP request.
- **The returned `Response`** answers the request.

If you know the Web `Request` and `Response` objects, you know the code model.
```

A mesma página fecha com o roteador, indexado pelo que o leitor quer fazer e não pelo título das páginas:

```mdx
import DocCardGroup from '@aziontech/webkit/doc-card-group'
import DocCard from '@aziontech/webkit/doc-card'

## Next steps

<DocCardGroup cols={2}>
  <DocCard title="Quickstart" href="/en/documentation/platform/functions/quickstart/" label="Run your first function now." />
  <DocCard title="How Functions works" href="/en/documentation/platform/functions/how-it-works/" label="Understand what invokes a function." />
  <DocCard title="Handlers" href="/en/documentation/devtools/runtime/api-reference/handlers/" label="Look up a handler, a parameter, or a limit." />
  <DocCard title="Glossary" href="/en/documentation/platform/functions/glossary/" label="Look up a term." />
</DocCardGroup>
```

## Relacionados

- [Referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia.md): A forma base que a visão geral aplica.
- [Páginas de quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart.md): A página para onde a visão geral envia o leitor.
- [Arquitetura de informação](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao.md): Onde a visão geral fica na seção do 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.