Páginas de glossário

Propósito

Um glossário define os termos que a documentação de um produto usa. É material de consulta: o leitor chega com uma palavra, encontra a definição e segue um link quando a definição não basta.

Um glossário guarda o vocabulário específico da Azion: produtos, recursos da plataforma, features e os termos que a Azion usa do seu próprio jeito. Um termo genérico da indústria, como CDN, serverless ou virtual machine, pertence ao Learning Center, não a um glossário da documentação. Um termo que a indústria também usa, mas que a Azion usa de forma diferente, mantém a entrada aqui e aponta o Learning Center para o sentido genérico.

Não é uma página de regras de nomes. Os nomes de produto pertencem à Terminologia da documentação; o glossário define o que os termos significam para o leitor.

Quando usar

Toda seção de produto carrega um glossário, um slot obrigatório do esqueleto da seção de produto. Escreva o glossário quando a seção é construída, e estenda quando uma página introduz um termo que o leitor precisa dominar para acompanhar a prosa.

Não escreva uma entrada para um termo que nenhuma página usa. Não escreva uma entrada para um termo genérico da indústria: aponte o artigo do Learning Center na página que precisa dele. Não use o glossário para explicar em profundidade. Um termo que precisa de mais de três frases precisa de uma página de conceito, e a definição aponta para ela.

Registro

Descritivo: 25 palavras por frase. O tom é neutro e lexicográfico: uma definição diz o que o termo é, sem vender e sem história.

Estrutura

• Uma frase de orientação nomeando o produto cujos termos a página define.
• Um componente <GlossaryFilter> envolvendo uma tabela GFM, | Termo | Definição |. O componente adiciona a caixa de filtro e dá a cada linha uma âncora derivada do termo (#cache-key). Mecânica em Componentes.
• Nenhuma seção de fechamento. A tabela é a página.

Template

Regras

• As linhas ordenam alfabeticamente pelo termo, por idioma. A página em português alfabetiza pelo termo em português; termos da lista que fica em inglês mantêm a forma inglesa e ordenam por ela.
• Um termo fica em minúscula, a menos que seja um nome de produto ou outro nome próprio.
• Uma definição tem de uma a três frases, e a primeira diz o que o termo é. Aponte a página canônica no próprio texto da definição.
• Toda definição corresponde a uma página da documentação. O glossário registra como a documentação usa um termo; ele nunca introduz um.
• O glossário é uma estrutura de crosslinks. Cada definição aponta sua página canônica no próprio texto e as páginas onde o leitor encontra o termo. Toda entrada mantém um caminho de volta para a documentação.
• Mover uma entrada nunca quebra um crosslink. Quando uma entrada migra para o Learning Center, toda página que apontava a entrada recebe o novo destino na mesma mudança.
• Linhas em branco ao redor da tabela dentro do componente são obrigatórias, ou a tabela renderiza como um único parágrafo literal.

Exemplos

O primeiro glossário de produto é o glossário do Functions: 22 termos, cada definição apontando sua página canônica.

Relacionados