Hubs de navegação

Propósito

Um hub de navegação leva o leitor para dentro da documentação. Ele carrega links e uma frase de orientação, e nada mais.

Ele não aplica nenhuma forma base do Diátaxis. Um hub não ensina, não instrui, não descreve e não explica: ele direciona. Por isso ele não tem orçamento de frase para um texto que não deveria estar ali.

Quando usar

• Escreva um hub quando uma seção tem mais páginas do que o menu lateral consegue mostrar de forma legível.
• Escreva um para uma seção que reúne páginas de vários produtos, como uma área de solução do hub de guias, ou o índice de arquiteturas.
• Escreva um para o slot Guias e tutoriais de uma seção de produto, que é uma única linha na sidebar apontando para um hub, e não um dropdown. Arquitetura de informação carrega essa regra.

Não escreva um hub quando:

• A seção é um produto. Um produto abre com uma visão geral, que orienta e aponta.
• A página explicaria longamente do que a seção trata. Isso é uma página de conceito.
• O menu lateral já torna as páginas encontráveis. Um hub que duplica o menu é mais uma coisa para manter e mais uma coisa para desatualizar.

Registro

Descritivo: 25 palavras por frase, voz ativa, passiva apenas quando o agente é desconhecido. Tom: breve, claro, orientador. Estrutura de frases tem as regras.

Estrutura

As duas formas abrem e fecham do mesmo jeito. Só o corpo muda.

• Abertura: uma frase de orientação dizendo o que a seção contém.
• Fechamento: nenhum. O último link ou a última linha da tabela encerra a página.

Forma 1: links agrupados

O padrão. Use quando os destinos são diferentes entre si e o leitor precisa de uma frase para distinguir um do outro.

• Corpo: grupos de links sob headings ## em frase nominal.
• Forma do link: [Título](/caminho/) - uma frase sobre o que o leitor encontra lá.

Forma 2: uma tabela

Use quando o hub lista um conjunto homogêneo e o leitor escolhe por esforço e atualidade, e não por descrição. O slot Guias e tutoriais tem essa forma, porque cada linha é um how-to ou um tutorial do mesmo produto e uma frase por linha repetiria o título da página.

• Corpo: um <ProductGuidesSection>, sem headings ## e sem grupos.
• Colunas: nome, tipo, última atualização.
• A tabela é gerada, nunca digitada. Uma página aparece quando o catálogo de guias a marca com o produto, o tipo vem do catálogo e a data vem da última alteração da página, então o hub não fica fora de passo com as páginas que lista. O hub de um recurso também lista os guias dos produtos aninhados nele; um produto aninhado não tem hub próprio.

Template

Copie o template da forma que você precisa e substitua cada <placeholder>.

Links agrupados:

Uma tabela:

Regras

• Nenhum fechamento e nenhum outro texto. Uma frase de orientação; a explicação vai em uma página de conceito.
• Faça cada link justificar o seu lugar. Um hub é julgado pelo que ele deixa de fora; um hub que lista tudo não hierarquiza nada.
• Escreva descrições que diferenciam. Diga o que esta página dá que as vizinhas não dão.
• Agrupe quando a lista passa de sete, pelo que o leitor está tentando fazer. Uma tabela não agrupa: ela ordena, da mais recente para a mais antiga. O grupo Recursos da plataforma da sidebar raiz é a única exceção: todos os recursos de plataforma na ordem em que o leitor os adota, por decisão, porque agrupá-los por intenção traria de volta os pilares aposentados.
• Escolha a forma pelo que o leitor compara. Destinos variados precisam de uma frase cada, então pedem links agrupados. Um único tipo de página, comparado por esforço e atualidade, pede a tabela.
• Nunca escreva uma linha de tabela à mão. Uma data digitada fica errada na primeira vez que alguém esquece, e é por isso que este é o único lugar em que o guia permite uma data fora de um changelog.
• Registre a página no catálogo de guias. Uma página que o catálogo não lista falta no hub. O primeiro produto que o catálogo indica para uma página é o dono dela e dá nome ao tópico dela na seção de Guias.
• Mantenha o hub em dia com a seção. Atualize o hub na mesma mudança que adiciona uma página.
• Defina type: homepage somente em um hub em grade de cards. Todas as outras páginas omitem o campo. Para mais informações, consulte Frontmatter.

Exemplos

• Casos de uso - Uma linha de orientação, e depois os designs agrupados por solução.
• Guias e tutoriais do Cache - A forma em tabela: uma frase, e depois cada guia e tutorial com seu tipo e sua data.

Um hub de Object Storage, cortado até a frase de orientação e o primeiro grupo. O exemplo está em inglês; a versão em português segue a mesma forma:

Relacionados