# 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](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/). 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](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/) | | Realizar uma tarefa específica que já tem em mente | [Guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) | | Consultar um fato: um limite, um campo, um flag, um código de resposta | [Referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/) | | Entender por que algo funciona do jeito que funciona | Explicação, como página de [conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/) ou [arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/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](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao/) 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](/pt-br/documentacao/guia-de-estilo/conteudo/visao-geral/) | Referência | Sim | A raiz do produto: o que o produto é, o que faz, quando usar | | [Quickstart](/pt-br/documentacao/guia-de-estilo/conteudo/quickstart/) | Tutorial | Sim | De não usar o produto ao menor resultado funcional | | [Tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/) | Tutorial | Não | Ensinar o produto ao construir um objetivo que o autor escolheu | | [Guia how-to](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) | How-to | Não | Completar uma tarefa com a qual o leitor chegou | | [Guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/) | How-to | Não | Alcançar um objetivo que cruza produtos, em um caminho recomendado | | [Caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-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](/pt-br/documentacao/guia-de-estilo/conteudo/troubleshooting/) | How-to | Não | De um sintoma que o leitor vê a um conserto | | [Referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia/) | Referência | Não | Consultar campos, valores, padrões e limites | | [Conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/) | Explicação | Não | Entender como algo funciona e por que é construído assim | | [Arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/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](/pt-br/documentacao/guia-de-estilo/conteudo/changelog/) | Registro | Não | Registrar mudanças notáveis, somente por acréscimo | | [Glossário](/pt-br/documentacao/guia-de-estilo/conteudo/glossario/) | Referência | Sim | Definir os termos que a documentação do produto usa, em uma tabela filtrável | | [Hub de navegação](/pt-br/documentacao/guia-de-estilo/conteudo/hubs-de-navegacao/) | 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](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao/#produtos-aninhados). ## 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](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura-de-informacao/) 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](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). Um caso de uso do catálogo, construído do início ao fim, é um [caso de uso](/pt-br/documentacao/guia-de-estilo/conteudo/casos-de-uso/). O raciocínio por trás de um design é uma página de [conceito](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/) ou de [arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/arquitetura/). - **Guia de integração com terceiros**: um guia how-to que cruza a interface de um fornecedor. As [regras de terceiros](/pt-br/documentacao/guia-de-estilo/conteudo/guias-how-to/) 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](/pt-br/documentacao/guia-de-estilo/conteudo/conceito/) ou [arquitetura](/pt-br/documentacao/guia-de-estilo/conteudo/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 |