Escolher um tipo de conteúdo

Escolha a forma pelo objetivo do leitor

Toda página de documentação é escrita em uma de quatro formas base, do Diátaxis. A forma decide a estrutura da página e as suas regras de frase. Escolha a forma pelo que o leitor quer fazer, não pelo que você quer escrever.

O leitor quer	A forma é
Aprender o produto ao construir algo que funciona	Tutorial
Realizar uma tarefa específica que já tem em mente	Guia how-to
Consultar um fato: um limite, um campo, um flag, um código de resposta	Referência
Entender por que algo funciona do jeito que funciona	Explicação, como página de conceito ou arquitetura

As formas respondem “como escrevo esta página”. O catálogo de tipos de página responde “qual página eu construo”.

Os tipos de página

Um tipo de página é uma forma base mais um lugar na arquitetura de informação e um template. Este é o catálogo completo. Toda página da documentação é um destes tipos.

Tipo	Forma base	Obrigatório por produto	Propósito
Visão geral	Referência	Sim	A raiz do produto: o que o produto é, o que faz, quando usar
Quickstart	Tutorial	Sim	De não usar o produto ao menor resultado funcional
Tutorial	Tutorial	Não	Ensinar o produto ao construir um objetivo que o autor escolheu
Guia how-to	How-to	Não	Completar uma tarefa com a qual o leitor chegou
Guia multiproduto	How-to	Não	Alcançar um objetivo que cruza produtos, em um caminho recomendado
Caso de uso	How-to	Não	Construir um caso de uso do catálogo do início ao fim, como uma spec que um agente segue
Troubleshooting	How-to	Não	De um sintoma que o leitor vê a um conserto
Referência	Referência	Não	Consultar campos, valores, padrões e limites
Conceito	Explicação	Não	Entender como algo funciona e por que é construído assim
Arquitetura	Explicação	Não	Uma arquitetura de referência do catálogo: como produtos e recursos da plataforma se combinam em um design
Changelog	Registro	Não	Registrar mudanças notáveis, somente por acréscimo
Glossário	Referência	Sim	Definir os termos que a documentação do produto usa, em uma tabela filtrável
Hub de navegação	Nenhuma	Não	Direcionar leitores para dentro. Links mais uma frase de orientação

Obrigatório por produto significa obrigatório por seção. Um produto aninhado como dropdown em um recurso da plataforma precisa somente das páginas de referência, e de um Quickstart quando tem uma configuração inicial própria; toda outra página que ele teria é uma seção das páginas do recurso. A regra de aninhamento está em Arquitetura de informação.

Slots não são tipos

Um slot é uma posição na seção de produto; um tipo é o formato de uma página. A arquitetura de informação lista treze slots, e este catálogo tem treze tipos. O tamanho igual é coincidência: as duas listas não se mapeiam uma na outra.

Vários slots compartilham um tipo. Limites, Exemplos e Features contêm páginas de referência, colocadas em slots diferentes porque o leitor chega a elas em momentos diferentes. Best practices e Como funciona contêm páginas de conceito. Um slot também pode conter vários tipos: Guias e tutoriais contém um hub de navegação, os guias how-to e os tutoriais. Adicionar um slot nunca adiciona um tipo, e uma página que não cabe em nenhum tipo é uma página cujo tipo de conteúdo ainda não foi decidido.

Tipos que a Azion não usa

Alguns tipos comuns em outras documentações estão ausentes de propósito, porque cada um se dissolve no catálogo:

FAQ: uma lista de perguntas é uma lista de páginas disfarçada. Direcione cada resposta ao seu tipo, e a pergunta vira um heading que a busca encontra.
Configuration: exemplos de configurações e valores são conteúdo de referência. O tipo adiciona um segundo nome para a mesma página.
Guias de design, implementação e solução: três nomes para conteúdo que o catálogo já tem. Um objetivo que cruza produtos é um guia multiproduto. Um caso de uso do catálogo, construído do início ao fim, é um caso de uso. O raciocínio por trás de um design é uma página de conceito ou de arquitetura.
Guia de integração com terceiros: um guia how-to que cruza a interface de um fornecedor. As regras de terceiros cobrem esse caso.
Página de solução: uma solução vive no site, não na documentação. Aqui uma solução é o rótulo de uma área de Guias e de um grupo de Architectures. As páginas são os casos de uso e as arquiteturas sob ela.
Diretrizes de API ainda não são cobertas por este guia.

Separe tutoriais de guias how-to

Tutoriais e guias how-to contêm passos. Eles servem leitores opostos, e essa é a distinção que mais importa.

O leitor de tutorial ainda não sabe o que quer. Ele aprende, e você ensina. Você escolhe o objetivo, garante o resultado e mantém as decisões longe do leitor. “Faça o deploy da sua primeira aplicação” é um tutorial: o leitor não tem uma aplicação em mente, e qualquer aplicação serve.

O leitor de how-to já sabe o que quer. Ele chegou com um problema. Você remove obstáculos; você não ensina. “Configurar políticas de cache” é um how-to: o leitor tem um problema de cache e quer o problema resolvido.

Dois testes separam as formas na prática. Se você escreve “você também pode” ou “dependendo da sua configuração”, a página é um how-to, porque tutoriais não ramificam. Se você interrompe os passos para explicar o que é um bucket, a página é um tutorial ou uma página de conceito, não um how-to.

Separe referência de conceito

Referência e explicação descrevem; nenhuma das duas formas instrui. Elas diferem no uso: uma é um mapa que o leitor consulta, a outra é uma discussão que o leitor lê.

Referência é o mapa. Ela é completa, consistente e deliberadamente simples. Ninguém lê uma referência de cima a baixo. Se o leitor que procura um valor de limite pula uma frase, essa frase não pertence à página.

Explicação é a discussão. Ela traz contexto, alternativas e razões. É a única forma onde “por quê” e “em vez de” pertencem. Uma decisão de design, uma comparação entre abordagens ou o contexto de uma funcionalidade vivem em uma página de conceito ou arquitetura e em nenhum outro lugar.

Separe guias multiproduto de casos de uso

As duas formas partem do how-to e as duas cruzam produtos, então vale declarar a divisão.

Um guia multiproduto parte de um objetivo técnico. O leitor sabe o que quer construir e precisa da rota entre os produtos. Ele termina quando a tarefa está feita.

Um caso de uso parte de uma entrada do catálogo: uma situação de cliente que o catálogo de casos de uso já nomeia e posiciona sob a sua solução. O leitor chega com uma situação, não com uma tarefa. A página nomeia os produtos que o cenário exige, mostra a arquitetura, configura tudo e prova que funciona. Ele é escrito como uma especificação que um agente executa. É por isso que carrega uma tabela de requisitos e um resultado mensurável, que o guia multiproduto não tem.

O teste tem dois passos. Primeiro, ligue o objetivo ao catálogo de casos de uso: uma entrada faz da página um caso de uso, qualquer que seja a redação do objetivo. Sem entrada, um objetivo que o leitor declara sem uma situação de cliente é um guia multiproduto. Uma situação de cliente que o catálogo deveria ter é uma proposta de entrada nova, não uma página.

Mantenha uma forma por página

Uma página que mistura formas é o defeito estrutural mais comum em documentação. Uma página de referência que para no meio para guiar o leitor pelo Console é duas páginas em um arquivo. O mesmo vale para um how-to que pausa para explicar arquitetura, ou um tutorial que vira uma tabela de parâmetros no meio do caminho.

O teste é barato: leia a página uma vez como cada um dos quatro leitores das formas base. Se dois deles querem metades diferentes, são duas páginas. Divida.

Conecte as formas entre si

Uma forma por página funciona porque links conectam as páginas. Cada forma aponta em uma direção previsível.

Uma página desta forma	Aponta para	Quando
Tutorial	Os guias how-to do seu produto	Em uma seção final “Próximos passos”
Guia how-to	Referência	Para cada configuração que os passos tocam
Referência	O guia how-to que muda uma configuração	Com parcimônia: no máximo um link por configuração
Conceito ou arquitetura	A referência e os guias que implementam o design	Onde o design encontra a prática

Duas regras mantêm os links verificáveis:

Toda página fecha com links. A página termina com o fechamento que o tipo dela exige, ## Próximos passos ou ## Recursos relacionados, com pelo menos um link para uma página da documentação. Glossário, changelog e hubs de navegação são as exceções, porque cada um já é uma lista de links.
Sem becos sem saída. Pelo menos um link do fechamento leva mais fundo no produto da própria página: uma página daquele produto que não seja a visão geral. Um fechamento cujos links apontam todos de volta para onde o leitor veio é um beco sem saída vestido de seção de fechamento.

A reciprocidade só é exigida na espinha do produto: a visão geral aponta para toda página da seção, e toda página da seção aponta para a visão geral. Entre quaisquer outras duas páginas o link corre em um sentido só.

Leia todas as páginas de tipo de conteúdo do mesmo jeito

Cada página desta seção descreve um tipo de conteúdo ou um padrão, e todas usam as mesmas seções na mesma ordem. Quando você sabe onde uma regra fica em uma página, você sabe onde ela fica em todas.

Seção	Responde
Propósito	O que esse tipo de página faz, e o que ela não é
Quando usar	Quando escrever uma, e quando escrever outra coisa
Registro	Procedural ou descritivo: o limite de frase, e o tom em poucos adjetivos
Estrutura	Os componentes obrigatórios e opcionais
Template	O esqueleto para copiar
Regras	As regras específicas desse tipo de página
Exemplos	Páginas que seguem o padrão
Relacionados	As páginas vizinhas neste guia