Referência

Propósito

Uma página de referência é material de consulta. O leitor a consulta para encontrar um valor, um campo ou um limite, e depois sai.

Quando usar

Escreva uma página de referência quando:

• O leitor precisa consultar um campo, uma configuração, um limite ou uma flag.
• A informação é enumerável e cabe em uma tabela.

Não escreva uma página de referência quando:

• O leitor precisa de passos para uma tarefa. Escreva um guia how-to.
• O leitor precisa do raciocínio por trás de um design. Escreva uma página de conceito.

Registro

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

Estrutura

Componentes obrigatórios

• Título: uma expressão nominal que nomeia a coisa: Object Storage, Configurações de cache, azion create bucket.
• Abertura: uma a três frases definicionais sobre o artefato, e depois direto para os dados. Sem enquadramento de procedimento.
• Seções: ##s como expressões nominais que nomeiam o objeto, o grupo de campos ou o nível real. As tabelas carregam a informação — campos, valores, padrões, limites — com fraseado consistente em cada coluna e unidade em cada número. A prosa entre as tabelas é uma ou duas frases de orientação.
• Limites: uma seção ## Limites quando o produto os tem, dimensionada por plano. Use | Escopo | Plano | Limite | quando um escopo se repete entre planos, ou uma coluna por plano quando o conjunto é curto o bastante para ler na horizontal. Cada linha carrega sua unidade e diz se o limite é rígido ou ajustável.
• Fechamento: ## Recursos relacionados, uma lista de DocItem cobrindo a página de conceito e os principais how-tos, cada linha com seu motivo.

Componentes opcionais

• Asides: uma dica acima da tabela de limites quando o suporte pode aumentar os limites, e um aviso de atenção para uma mudança de versão ou de migração. Não use outros asides.

As seções mantêm essa ordem.

Quando o conjunto de limites cresce o bastante para ser consultado sozinho, ele vai para o slot Limites da seção de produto. Estas regras não mudam: só o lugar muda. Arquitetura de informação tem a lista de slots.

Template

Copie o template e substitua cada <placeholder>:

Regras

• Nunca um passo a passo numerado. No momento em que um aparece, a página é um guia how-to arquivado no lugar errado. Aponte para o how-to.
• Seja completo antes de ser interessante. Uma referência sem três de doze campos está quebrada; uma com descrições sem graça dos doze cumpre o papel.
• Coloque informação enumerável em tabelas. Campos, limites, flags, padrões, códigos de status.
• Mantenha o fraseado consistente na coluna. O leitor escaneia; fraseado variado obriga a ler.
• Declare as unidades e os valores padrão. Um limite sem unidade não é um fato.
• Dimensione todo limite por plano. Um limite que muda entre planos não é um fato só. Um número publicado sem o plano a que pertence está errado para todo leitor que está em outro plano.
• Separe limite de valor padrão. Um valor padrão é um campo e fica na tabela de campos. Um limite é um teto e fica em ## Limites.
• Diga se cada limite é rígido ou ajustável. A próxima ação do leitor depende disso: um limite ajustável é um chamado no suporte, um limite rígido é uma restrição de design.
• Nunca invente um limite nem um nome de plano. Tire os dois da página de pricing, do contrato de planos ou do time de produto. Um valor que você não consegue confirmar não é publicado: estreite a tabela até as dimensões que você consegue confirmar.
• Nunca repita um preço. Valores, cotas vendidas por unidade e métricas de cobrança vivem só na página de pricing. Aponte para ela; não copie.
• Sem marketing. Diga o que faz e onde para.
• Uma página de comando da CLI tem sua própria forma. Um resumo de uma linha, depois ## Uso com o comando, depois ## Flags opcionais com uma entrada por flag.

Exemplos

Este exemplo, em inglês, mostra a abertura definicional, uma seção de objeto com sua tabela e o fechamento de uma referência de Object Storage:

Este exemplo mostra uma tabela de limites em que a separação por plano não foi confirmada. A tabela carrega as colunas que foram confirmadas e nada mais:

A coluna ausente é o ponto. A separação por plano desses números não foi confirmada, então a tabela não tem coluna de plano, em vez de uma coluna inventada.

Relacionados