Procedimentos

O primeiro passo

Todo procedimento numerado da documentação segue estas regras, em qualquer tipo de página. A primeira regra consolida acesso e navegação em um único passo. Não faça de “Log in” um passo próprio quando o passo seguinte é ir a algum lugar.

Procedimentos no Console começam com a string canônica:

Preencha o produto: > **Object Storage**, > **Firewall**. Uma navegação mais profunda estende a cadeia: > **Applications** > **sua aplicação**.

Um procedimento de um único comando não é uma lista numerada. Escreva uma frase de introdução terminada em dois-pontos e depois o comando:

A numeração começa quando o procedimento tem duas ou mais ações. A introdução de um procedimento de API nomeia o método e o endpoint: “Envie uma requisição POST para o endpoint de buckets:” e depois o bloco curl.

Uma ação por passo

Um passo com duas ações é um passo em que a segunda ação é pulada.

• Incorreto: Selecione **Save**, depois faça o purge do cache e confirme a mudança do TTL.
• Correto: três passos numerados, um para cada ação.

Movimentos pequenos que formam um único gesto podem dividir um passo, e portanto uma única frase: Digite um nome e selecione **Read Only**. Este é o único lugar em que uma frase carrega dois imperativos, e ele prevalece sobre as regras de frase em Estrutura de frases.

Ordem dentro de um passo

O leitor se orienta, depois age. A localização vem antes da ação:

• Incorreto: Selecione **Add Rule** na aba Rules Engine.
• Correto: Na aba **Rules Engine**, selecione **Add Rule**.

A finalidade vem antes da ação. Quando um passo existe por uma razão que o leitor não pode ver, comece por ela: Para excluir a regra, selecione **Delete**.

A condição vem antes da ação: Se a lista estiver vazia, selecione **Add**.

Gramática do passo

• Escreva no imperativo, na voz ativa e no presente: Selecione **Save**. Nunca “Você deve selecionar” ou “O botão Save deve ser selecionado”.
• Comece um passo opcional com a palavra literal (Opcional): 3. (Opcional) Digite uma descrição para a regra.
• Marque subpassos com letras minúsculas (a., b.) e o nível seguinte com números romanos minúsculos. Se um passo precisa desse terceiro nível, o procedimento pede divisão.
• Use negrito no rótulo da interface e itálico no valor: Defina **Workloads Access** como _Read Only_.
• Use apenas os verbos da interface. Em inglês: select, go to, turn on, turn off, enter; nunca click, hit, enable, disable. Em português, os procedimentos usam acesse, selecione, digite e defina; nunca clique. A tabela está em Escolha de palavras.
• Use as palavras da própria interface. Se o botão diz Save, o passo diz selecione Save, não “confirme” ou “aplique”. Não melhore o vocabulário da interface na prosa que a descreve.
• Não use linguagem direcional. Nomeie o elemento, não onde ele fica na tela, conforme Acessibilidade.
• Mantenha cada frase em 20 palavras e cada passo com uma instrução. O orçamento procedural está em Estrutura de frases.

A frase de introdução

Imediatamente antes da lista numerada, uma frase declara o objetivo e termina em dois-pontos:

Use dois-pontos quando a frase precede os passos imediatamente. Use ponto final quando algo fica entre eles, como um aside. Nunca escreva uma frase parcial que os passos completam.

Depois do procedimento

Termine todo procedimento com uma frase de resultado. Diga o que o leitor agora tem ou vê, para que ele saiba que teve sucesso sem perguntar.

• O bucket aparece na lista de buckets.
• A resposta retorna "state": "executed" com o nome do bucket.

Quando a interface não mostra saída, declare o estado resultante: O bucket tem o novo nível de acesso. Nunca escreva saída da interface, códigos de resposta, headers ou mensagens que você não viu o produto produzir. Essa distinção separa uma frase de resultado de um fato inventado.

Avise sobre o tempo de propagação. Se um resultado demora a propagar, diga isso e diga o que fazer: “Novas regras podem levar alguns minutos para propagar. Diante de uma resposta inesperada, aguarde e tente novamente antes de diagnosticar.”

Tarefas seguintes vão para a seção ## Próximos passos da página, nunca para uma seção de “pós-requisitos”.

Mostre o output esperado

Todo comando que o leitor executa é seguido do output que ele deve ver. Mostre o output completo quando ele é curto, e o trecho relevante quando ele é longo. O output confirma que o passo funcionou antes que o próximo passo dependa dele.

Input e output usam blocos diferentes: um bloco <Code> para o comando que o leitor copia, um fence para o output que ele lê. A mecânica está em Componentes.

Quando um comando não produz output, declare o estado resultante. Quando não é possível declarar nenhum dos dois, corte o comando ou reestruture o passo em torno de um resultado que o leitor consegue conferir: um comando que o leitor não consegue verificar é pior do que um comando a menos. Nunca escreva um output que você não viu o comando produzir.

Múltiplas interfaces

Quando uma tarefa tem um caminho no Console, na CLI e na API, os caminhos vão em um bloco <Tabs>: um procedimento por painel, com o Console primeiro. Cada painel abre com a própria frase de introdução nomeando a interface: Para criar o bucket com a Azion CLI:. Os passos ou o comando vêm em seguida, e a introdução nunca é repetida como um passo. Nunca misture duas interfaces em uma mesma lista numerada. A mecânica do bloco <Tabs> está em Componentes.

Inclua um painel só quando tiver executado o procedimento dele do início ao fim. Deixe de fora uma interface que você ainda não consegue verificar, em vez de preencher os passos dela a partir dos outros painéis.