Um how-to guide é um tipo de documentação que fornece instruções específicas sobre como realizar determinada tarefa. Esse tipo de texto foca nos aspectos práticos de um processo, geralmente com instruções detalhadas e recursos visuais. Os how-to guides são destinados a usuários que desejam atingir um objetivo específico e estão familiarizados com o produto ou módulo.

Neste documento, você verá um modelo, diretrizes gerais e exemplos de how-to guides.

Certifique-se de revisar as diretrizes em Melhores práticas para escrever documentação.

Este tipo de conteúdo é criado e disponibilizado somente em inglês.

Embora tanto o tutorial quanto o how-to guide sejam recursos com instruções, eles apresentam algumas diferenças em sua estrutura e finalidade:

Objetivo

Tutorial	How-to guide
Orientado à aprendizagem. Ensina um conceito, habilidade ou processo mais amplo em detalhes.	Orientado para tarefas. Foca em ajudar o usuário a concluir uma tarefa ou objetivo específico.

Escopo

Tutorial	How-to guide
Contempla uma série de etapas ou conceitos, frequentemente relacionados ao aprendizado de uma nova habilidade.	Tem um escopo restrito, geralmente aborda uma tarefa ou processo dividido em etapas.

Conteúdo

Tutorial	How-to guide
Educativo, oferecendo contexto e explicações adicionais.	Prático, com instruções diretas e focadas em tarefas.

Público-alvo

Tutorial	How-to guide
Usuários que desejam aprender uma habilidade ou entender um conceito de forma detalhada.	Usuários que precisam alcançar rapidamente um objetivo específico, geralmente com conhecimento prévio.

Tema	Descrição
Título	Indique diretamente o objetivo do guia e use um verbo no gerúndio. Leve em consideração o seu público-alvo e a ação específica que você deseja que realizem. Exemplo: Setting up your development environment
Antes de começar (opcional)	Liste todos os pré-requisitos que o usuário precisa cumprir ou concluir antes de seguir as etapas do guia, incluindo: Requisitos de ferramentas e software: especifique os requisitos mínimos do sistema, como versões do sistema operacional, instalações de software específicas e configurações de hardware. Criação ou configuração de conta: se o usuário precisar criar uma conta ou definir configurações específicas, forneça instruções claras ou links para recursos relevantes. Conhecimentos ou habilidades básicas: se o guia pressupõe um certo nível de familiaridade com conceitos ou ferramentas específicos, descreva brevemente esses pré-requisitos ou forneça links para recursos de aprendizagem adicionais.
Instruções	Fornece instruções detalhadas para concluir a tarefa ou atingir o objetivo. Divide o processo em etapas, garantindo que cada uma delas seja clara e acionável. Considera o que o usuário precisa realizar até o fim do guia e descreve todas as tarefas necessárias para isso. Por exemplo, se o objetivo é configurar um ambiente de desenvolvimento para criar uma loja virtual, considere cada tarefa que o usuário precisa realizar para configurar esse ambiente. Se um guia exigir apenas uma etapa, omita a Etapa 1 - Título da etapa e, na seção Instruções, liste as ações em uma lista ordenada. Cada etapa deve guiar o usuário de um ponto a outro em uma sequência lógica. Quando relevante, inclua exemplos, mídia ou avisos para ajudar os usuários. A última etapa deve apresentar o resultado para que o usuário possa compará-lo com os seus próprios resultados.
Conteúdo das instruções	Cada linha das instruções deve corresponder a uma ação a ser realizada pelo usuário. Não assuma que o usuário já tem determinado conhecimento. Por exemplo, se o usuário precisar pressionar a tecla Enter em uma etapa, inclua essa instrução como parte da instrução. Use colchetes angulares (>) para dividir etapas complexas ou combinar etapas simples para ações sequenciais. Exemplo: 1. In the VTEX Admin, go to Storefront > Site Editor. Mantenha a consistência do tempo verbal ao longo das instruções usando verbos no imperativo. Exemplo: 1. Click File > New > Document..

Modelo de how-to guide

# Título

[Descreva nesta seção o objetivo do guia e o que o usuário poderá fazer após segui-lo.]

## Antes de começar

[Liste todas as ferramentas, softwares, contas, conhecimentos ou habilidades que o usuário deve ter antes de começar a seguir o guia.]

## Intruções

### Passo 1 - Título do passo 1

[Dê as instruções para esta etapa.]

### Passo 2 - Título do passo 2

[Dê as instruções para esta etapa.]

### Passo 3 - Título do passo 3

[Dê as instruções para esta etapa.]

• Overriding native component's props
• Managing product images in specific contexts
• Building a search results page with multiple layouts
• Running IO scripts in non-IO VTEX stores