# Guias how-to ## Propósito Um guia how-to leva um leitor com um problema até o problema resolvido. O leitor já sabe o que quer. A página remove os obstáculos entre ele e o resultado; ela não ensina. ## Quando usar - O leitor chegou com uma tarefa específica e uma situação real. - Não use um how-to para o leitor que está aprendendo o produto: essa página é um [tutorial](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais/). - Um how-to cuja tarefa é um conserto é uma [página de troubleshooting](/pt-br/documentacao/guia-de-estilo/conteudo/troubleshooting/). - Na dúvida, [Escolher um tipo de conteúdo](/pt-br/documentacao/guia-de-estilo/conteudo/escolher-um-tipo-de-conteudo/) tem o roteiro. ## Registro Procedural: 20 palavras por frase, uma instrução por passo, imperativo e ativo. Tom: diretivo, claro, eficiente. [Estrutura de frases](/pt-br/documentacao/guia-de-estilo/escrita/estrutura-de-frases/) tem as regras. ## Estrutura **Componentes obrigatórios** - **Frase de escopo**: a abertura declara, em uma frase, o que a página permite ao leitor fazer e a partir de onde. Nunca `Neste guia`. - **Pré-requisitos**: uma seção `## Pré-requisitos` quando a página tem algum, em lista; cada item é um link ou um comando de uma linha. Um único pré-requisito é uma frase, não uma lista. - **Seções de tarefa**: um `##` por tarefa, cada um uma frase verbal no imperativo. - **Lead-in**: logo antes de cada procedimento, uma frase terminada em dois-pontos, como `Para criar o bucket:`. - **Frase de resultado**: todo procedimento termina declarando o que o leitor agora tem ou vê. - **Próximos passos**: uma seção final `## Próximos passos`, um `DocCardGroup` com um ou dois cards: o título, o link e o motivo como texto do card. **Componentes opcionais** - **Tabs por interface**: um bloco `` quando uma tarefa roda em mais de uma interface, painel do Console primeiro, um procedimento completo por painel. - **Um aside** com o caminho alternativo, quando a tarefa genuinamente ramifica. ## Template Copie o template e substitua cada ``. ```mdx import DocCardGroup from '@aziontech/webkit/doc-card-group' import DocCard from '@aziontech/webkit/doc-card' [Uma frase de escopo: o que a página permite ao leitor fazer, e a partir de onde.] ## Pré-requisitos - --- ## Para : 1. 2. --- ## --- ## Próximos passos ``` Separe as seções principais da página com uma régua `---`, e nunca coloque uma logo depois do frontmatter. ## Regras - **Nomeie a tarefa no título.** Uma frase verbal curta no imperativo: `Criar um bucket`, `Alterar as permissões de um bucket`. Não um gerúndio, não uma pergunta, não um prefixo `Como ...` — o verbo carrega o título. O prefixo está aposentado em páginas novas e reescritas. - **Abra com uma frase de escopo.** Declare o que a página permite ao leitor fazer e a partir de onde: `Você pode criar um bucket pelo Azion Console, pela Azion CLI ou pela API.` - **Uma tarefa por heading.** Um heading que cobre duas tarefas vira dois headings. - **Acrescente informação depois de cada heading.** A primeira frase de uma seção de tarefa deve acrescentar informação que o heading não dá; o lead-in carrega a seção. - **Siga as regras de passos.** Os passos seguem [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/), e todo procedimento termina com sua frase de resultado. - **Mostre o output depois de cada comando.** O leitor vê como o sucesso se parece antes que o próximo passo dependa dele. A regra está em [Procedimentos](/pt-br/documentacao/guia-de-estilo/escrita/procedimentos/). - **Ramifique onde a tarefa ramifica.** Tarefas com mais de uma interface usam um bloco ``, painel do Console primeiro — nunca seções sequenciais por interface. - **Não ensine.** Uma frase de contexto, depois os passos. Um parágrafo de contexto pertence a uma página de conceito; aponte para ela. - **Use um verbo por ação**, em todas as menções da página. - **Aponte para os vizinhos.** Guias how-to irmãos e a página de referência do produto, no corpo ou em `## Próximos passos`. - **Mande um objetivo que cruza produtos** para um [guia multiproduto](/pt-br/documentacao/guia-de-estilo/conteudo/guias-multiproduto/). - **Aponte para fora em produtos de terceiros.** Nomeie o passo do fornecedor; não documente a interface dele. ## Exemplos O trecho a seguir mostra a frase de escopo, os pré-requisitos e o painel do Console da primeira tarefa: ```mdx Você pode criar um bucket do [Object Storage](/pt-br/documentacao/plataforma/object-storage/) e alterar as permissões pelo Azion Console, pela CLI ou pela API. ## Pré-requisitos Para usar os procedimentos da CLI, você precisa da Azion CLI instalada e de um personal token configurado. --- ## Criar um bucket Console CLI API Para criar o bucket pelo Azion Console: 1. Acesse [Azion Console](https://console.azion.com/) > **Object Storage**. 2. Selecione **+ Bucket**. 3. Digite um **Bucket Name** de 6 a 63 caracteres. 4. Defina **Workloads Access** como _Read Only_, _Read-Write_ ou _Restricted_. 5. Selecione **Save**. O bucket aparece na lista de buckets. ``` - [Crie regras de request e response](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/primeiros-passos/rules-engine/): duas tarefas em uma página, cada uma com passos numerados e imperativos. ## Relacionados - [Tutoriais](/pt-br/documentacao/guia-de-estilo/conteudo/tutoriais.md): A página para o leitor que está aprendendo. - [Páginas de troubleshooting](/pt-br/documentacao/guia-de-estilo/conteudo/troubleshooting.md): O how-to cuja tarefa é um conserto. - [Referência](/pt-br/documentacao/guia-de-estilo/conteudo/referencia.md): Onde cada configuração que um guia toca está documentada.