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: é 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.
• O leitor precisa de passos para uma tarefa. Escreva um guia how-to ou um tutorial.
• O assunto é como produtos e recursos da plataforma se combinam em uma arquitetura de referência. Escreva uma página de 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 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>:

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 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.
• 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:

Relacionados