Arquitetura de informação

Esta página define a estrutura alvo da documentação da Azion. Seções novas seguem esta estrutura, e as seções existentes convergem para ela conforme são revisadas. Não copie a estrutura de uma seção existente: este padrão vence.

Dois princípios organizam tudo. As seções seguem a ordem da jornada do leitor com o produto. Cada seção contém um tipo de conteúdo, então a jornada decide onde a seção fica e o tipo decide como as páginas dela são.

O esqueleto de seção de produto

Toda seção de produto segue esta ordem. A tabela mostra o que cada slot contém e quando ele existe.

Um tipo de recurso da plataforma com seção própria (Workloads, Edge DNS, Applications, Connectors, Firewall) segue o mesmo esqueleto. A visão geral descreve o tipo de recurso, o quickstart cria a primeira instância, e Glossário, Pricing e Changelog são obrigatórios como em um produto. Um produto habilitado no recurso não mantém seção própria: ele entra na seção do recurso como uma linha dropdown na posição do slot 4, e a URL dele fica aninhada sob o recurso, como em /documentacao/plataforma/firewall/waf/. A regra de aninhamento e o que o dropdown contém estão em Produtos aninhados.

Dois slots têm uma forma fixa na sidebar.

Guias e tutoriais é uma linha que abre uma página. A linha aponta para um hub cujo corpo é uma única tabela: nome, última atualização e dificuldade, uma linha por guia e por tutorial. A sidebar nunca expande essa linha, e o leitor abre um guia a partir da tabela. Uma seção com quarenta guias continua sendo uma linha na sidebar, então a sidebar segue mostrando o produto inteiro.

A tabela é gerada, não escrita. A data é a da última alteração da página e a dificuldade vem do campo difficulty do frontmatter da página, então o hub não diverge das páginas que lista.

Referência é um grupo fixo. A sidebar mostra um pai Referência com uma linha por página de referência. O nome do grupo é o mesmo em toda seção de produto, então o leitor encontra os campos no mesmo lugar em todas.

Outras linhas podem se agrupar da mesma forma. Um grupo é um pai de menu, não uma página, e fica em um único nível. Dois modos existem:

• Grupos fixos guardam as páginas de um slot sob o nome padrão do slot. Referência é o caso canônico. O Quickstart se agrupa da mesma forma no único caso em que ainda se divide: um primeiro uso que a interface não consegue compartilhar.
• Grupos de mesmo tipo guardam páginas de fechamento relacionadas sob um pai temático. Gerenciamento guarda Limites, Preços e Changelog: as páginas que o leitor consulta sobre a operação do produto.

Não agrupe linhas que funcionam bem planas. Um pai custa um clique ao leitor em cada visita, então um grupo precisa se pagar.

Uma feature com superfície própria repete o padrão um nível abaixo: Tiered Cache sob Cache, com o mesmo esqueleto reduzido às partes de que precisa.

Produtos aninhados

Um produto habilitado em um recurso da plataforma é uma linha dropdown dentro da seção do recurso, na posição do slot 4, sem rótulo de grupo: WAF, Network Shield e Bot Manager dentro de Firewall; Cache, Application Accelerator e Image Processor dentro de Applications; Load Balancer e Origin Shield dentro de Connectors; Certificate Manager, Custom Pages e DDoS Protection dentro de Workloads. O produto mantém só as páginas que são dele: as páginas de referência e, quando tem uma configuração inicial própria, um Quickstart. Todo o resto que o leitor precisa saber sobre ele é escrito uma vez, nas páginas do recurso: o que o produto faz e quando ativá-lo na visão geral do recurso, como ele funciona na página Como funciona do recurso, os limites, as práticas e os sintomas nas páginas Limites, Boas práticas e Troubleshooting do recurso, os termos no glossário do recurso e os guias no hub do recurso.

Um produto se aninha quando a configuração dele vive nas configurações ou nas regras do próprio recurso: uma flag em modules, um behavior do Rules Engine ou um campo do recurso. Um produto ou recurso que o leitor consome do código (Functions, Object Storage, SQL Database, KV Store, AI Inference) e um serviço autônomo (Edge DNS, Data Stream, Orchestrator) ficam na raiz de Recursos da plataforma. Uma feature é uma página dentro do produto, nunca um dropdown. Um tipo de recurso da plataforma aninhado em outro, como Certificate Manager e Custom Pages em Workloads, segue a mesma regra.

O Quickstart carrega a interface dentro da página. Um produto cujo primeiro uso passa por Azion Console, pela Azion CLI ou pela API mantém uma página e seleciona a interface com tabs, então o slot tem uma linha e uma URL. O slot se divide apenas quando as interfaces não podem compartilhar um esqueleto de etapas, e para um agente de IA, cujo caminho é conduzido por prompt e não compartilha etapa com os outros. Essas páginas ficam agrupadas sob Quickstart, com o Console primeiro; o grupo é um pai da barra lateral, não uma página. Páginas de quickstart tem o teste.

A seção de onboarding de plataforma em /documentation/get-started/ é outra coisa com nome parecido. Quickstart é o slot por produto. Get started é a porta de entrada da plataforma, e não pertence a nenhum produto.

A ordem, e o que justifica um slot

• A ordem espelha a adoção. Um slot nunca fica à frente da sua etapa.
• Pricing e Changelog fecham a seção. O leitor os consulta em vez de passar por eles.
• A coluna Obrigatório decide o que é publicado. Todo outro slot existe somente quando conteúdo real o preenche. A coluna vale para uma seção; um produto aninhado precisa somente das páginas de referência, e de um Quickstart quando tem uma configuração inicial própria.
• Nunca adicione um slot para completar o padrão, e nunca mantenha um vazio como marcador.
• Cresça dividindo um slot que a seção já tem: Guias e tutoriais em grupos de tarefa nomeados na página de hub, Features por superfície. O Quickstart cresce dentro da própria página, por tabs de interface, e se divide apenas quando as etapas não podem ser compartilhadas.
• Os treze nunca aumentam em número.

Pricing e limites

• Pricing é um link, nunca uma página. O slot 12 aponta para /documentacao/fundamentos/precos/#<produto>. Confirme que a âncora resolve antes de publicar. Um produto aninhado não tem linha de Pricing; o link do recurso o cobre.
• Nunca repita um preço, uma cota ou uma métrica de cobrança em uma página de produto. Um preço duplicado fica errado no dia em que muda.
• Nomeie o plano quando a disponibilidade faz parte do comportamento, e use o link de pricing para os números.
• Limites são dimensionados por plano. Um número único esconde a diferença de todo leitor que está em outro plano.
• O contrato da tabela de limites fica em Referência: unidades, padrões e limites ajustáveis.
• Limites ocupam o slot 9 quando o conjunto vale ser consultado sozinho. Uma seção ## Limites na página de referência cobre um conjunto curto.

Posicione uma página nova

Conteúdo que nenhum produto possui sozinho vive ao lado dos produtos, não dentro de um deles. Decida pelo leitor que a página serve:

• A página documenta um produto: entra na seção desse produto, no slot que o tipo de conteúdo indica.
• A página explica a plataforma, contas ou billing: entra em Fundamentals.
• A página diagnostica problemas de plataforma ou leva ao time de suporte: entra em Suporte.
• A página constrói um caso de uso do catálogo: é um caso de uso, e entra em Guias, na área da solução da sua entrada.
• A página mostra uma arquitetura de referência do catálogo, como produtos e recursos da plataforma se combinam em um design: entra em Architectures, sob a sua solução.
• A página reúne links de uma área: é um hub de navegação, e precisa de um público real antes de existir.

Quando nenhuma seção serve, abra uma issue antes de criar uma. Uma seção nova muda a navegação para todos os leitores.