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.

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 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, com link a partir daqui.
• A página só listaria links. Isso é um hub de navegação.

Registro

Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é desconhecido. Tom: acolhedor, factual, direto. 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>:

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 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, 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:

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

Relacionados