Guias do usuário têm um problema de reputação. A maioria das equipes os escreve porque alguém precisa fazer isso, ninguém gosta da tarefa, e o resultado é uma pasta de documentos que descrevem a interface com precisão e não ajudam ninguém.
Os guias que funcionam têm algo específico em comum: são organizados em torno do que o usuário está tentando fazer, e não do que o produto contém. Essa única mudança explica a maior parte da diferença entre a documentação que as pessoas procuram e a que elas ignoram.
Este guia mostra os tipos de guia do usuário que valem a pena escrever, uma estrutura que funciona para cada um, oito exemplos de formatos de guia para copiar e o ponto em que a documentação escrita deixa de ser a ferramenta certa.
Toda boa página de guia tem o mesmo esqueleto, seja qual for o produto.
Principais conclusões
- Organize por tarefa, não por menu. Os usuários buscam o que querem fazer, nunca o nome da sua funcionalidade.
- Um guia, um resultado. Uma página que cobre três tarefas não será encontrada por ninguém que procure qualquer uma delas.
- Comece pelo resultado e pelos pré-requisitos. Em cinco segundos, o usuário precisa saber que está no lugar certo.
- Capturas de tela custam caro. Cada uma é um custo de manutenção; use-as só onde as palavras realmente não conseguem eliminar a ambiguidade.
- Em tarefas de primeira vez, guias escritos perdem para a orientação in-app. A documentação brilha em profundidade, referência e solução de problemas.
- Os tickets de suporte são o seu roadmap de conteúdo. As perguntas que as pessoas fazem são os guias que você ainda não escreveu.
O que é um guia do usuário?
Definição de guia do usuário: um documento que ajuda alguém a concluir uma tarefa específica com um produto, escrito do ponto de vista do usuário e estruturado em torno do objetivo dele, e não da arquitetura do software. Em SaaS, os guias do usuário costumam ficar em uma central de ajuda e convivem com a orientação dentro do produto, sem substituí-la.
Os termos se sobrepõem de um jeito confuso, então vale ser preciso sobre o que você está escrevendo:
| Formato | Responde a | Melhor estrutura | Tamanho |
|---|---|---|---|
| Guia de como fazer | "Como eu faço X?" | Passos numerados rumo a um único resultado | 300–800 palavras |
| Guia de primeiros passos | "Por onde eu começo?" | O caminho mais curto até o primeiro valor | 500–1.200 palavras |
| Referência | "O que essa configuração faz?" | Alfabética ou estrutural; fácil de escanear | O que for necessário |
| Guia conceitual | "Por que funciona assim?" | Prosa, diagramas, um exemplo prático | 800–2.000 palavras |
| Solução de problemas | "Por que isso não está funcionando?" | Sintoma → causa → correção | Curto, por sintoma |
Misturar esses tipos é a falha de documentação mais comum. Um guia de como fazer que para no meio para explicar a arquitetura perde quem está com pressa; um guia conceitual quebrado em passos numerados perde quem está tentando entender. Decida qual deles você está escrevendo antes da primeira frase.
Como criar um guia do usuário, passo a passo
Comece pela tarefa, nas palavras do usuário
Escreva primeiro o resultado e os pré-requisitos
Redija os passos fazendo a tarefa você mesmo
Inclua imagens só onde as palavras falham
Feche o ciclo: verificação, armadilhas, próximo passo
Teste com alguém que nunca fez a tarefa
Defina um responsável e uma data de revisão
1. Comece pela tarefa, nas palavras do usuário
Sua funcionalidade se chama "Segment Builder". Seus usuários buscam "como enviar isso só para clientes novos". Dê à página o título da busca, não o da funcionalidade; o nome da funcionalidade pode aparecer no corpo do texto, onde continuará sendo encontrado.
A melhor fonte dessas formulações é gratuita e já está no seu helpdesk: as palavras exatas dos tickets de suporte, mais as buscas feitas no seu site. As duas mostram como as pessoas chamam as coisas quando ninguém está olhando.
2. Escreva primeiro o resultado e os pré-requisitos
Antes do primeiro passo, responda a duas perguntas: o que o usuário terá quando terminar e do que ele precisa antes de começar (um nível de permissão, uma integração conectada, um objeto já existente). Pré-requisitos escondidos no quarto passo são o motivo pelo qual guias são abandonados no meio, com o trabalho feito pela metade.
3. Redija os passos fazendo a tarefa você mesmo
Escreva enquanto executa a tarefa no produto, não de memória nem a partir de uma especificação. A memória pula sem avisar os passos que se tornaram automáticos para você, e são justamente esses os passos em que um usuário novo trava.
Regras para os próprios passos: uma ação por passo, verbo primeiro ("Clique", "Selecione", "Digite") e o rótulo exato da interface em negrito. Se um passo precisa de um "enquanto isso" ou de um "observe que", são dois passos.
4. Inclua imagens só onde as palavras falham
Uma captura de tela para cada passo parece caprichado, mas é uma armadilha de manutenção: sua interface muda, e um guia com quinze capturas desatualizadas é pior do que um sem nenhuma, porque passa a informar errado. Use uma imagem quando o alvo for realmente difícil de descrever, quando o usuário precisar confirmar que está no lugar certo ou quando o resultado for visual. Nos outros casos, descreva com palavras.
Quando usar imagens, recorte bem a área relevante e faça anotações. Uma captura da janela inteira obriga o leitor a caçar o único controle de que a frase está falando.
5. Feche o ciclo: verificação, armadilhas, próximo passo
Três seções curtas que a maioria dos guias omite e que concentram a maior parte do valor:
- Como confirmar que funcionou: o sinal observável de sucesso, para que o usuário não precise adivinhar.
- O que costuma dar errado: os dois ou três problemas que o suporte mais vê, com a correção.
- A próxima tarefa natural: para onde costuma ir quem acabou de concluir esta.
6. Teste com alguém que nunca fez a tarefa
Entregue o rascunho a um colega de fora da equipe e observe-o seguir as instruções sem ajudar. Cada ponto em que ele hesita é um defeito. Isso leva quinze minutos e encontra mais problemas do que qualquer quantidade de revisão interna, porque quem revisa lê a documentação enquanto o conhecimento de quem escreveu ainda está na sala.
7. Defina um responsável e uma data de revisão
A documentação apodrece em silêncio. Um guia sem responsável nomeado e sem data de revisão estará errado em dois ciclos de release, e ninguém vai perceber até que um cliente perceba. Coloque na página uma data de última atualização visível; ela também mostra ao usuário se ele pode confiar no que está lendo.
8 formatos de guia do usuário que valem a pena copiar
Uma página, um resultado: o caminho mais curto possível de uma conta vazia até o primeiro resultado real. Ele ignora de propósito configurações, casos extremos e alternativas; tudo o que não está no caminho crítico vira um link, não um parágrafo.
Título no formato de tarefa, resultado e pré-requisitos no topo, de cinco a nove passos numerados, uma linha de verificação e dois problemas comuns. Nada mais.
Pontos de entrada paralelos ("Para administradores", "Para editores", "Para leitores"), cada um com seu próprio caminho curto pelo mesmo produto. A mesma funcionalidade aparece em mais de um guia, descrita de formas diferentes.
Organizado inteiramente pelo que o usuário observa, como "Minha importação terminou, mas nenhum registro apareceu", e nunca pela causa interna. Cada sintoma leva a uma ou mais causas, com uma correção específica.
Todas as opções em uma tabela fácil de escanear: nome, o que faz, valor padrão e (a coluna que a maioria das equipes omite) o que acontece se você mudar a opção depois da configuração inicial.
Um cenário realista de ponta a ponta, com nomes e números concretos, mostrando como várias funcionalidades se combinam para resolver um problema real, e não um tour de funcionalidades disfarçado de história.
Uma gravação de 60 a 120 segundos, sempre acompanhada dos mesmos passos em texto na mesma página.
O guia roda dentro da aplicação, destacando os controles reais em sequência enquanto o usuário executa a tarefa com os próprios dados.
As mesmas instruções de um guia do usuário escrito, entregues na tela real que o usuário está vendo.
Quando um guia escrito é a ferramenta errada
A documentação tem uma desvantagem estrutural que nenhuma boa escrita resolve: ela exige que o usuário saia do produto, encontre a página certa, guarde as instruções na cabeça e volte. Em uma tarefa de primeira vez, em uma interface desconhecida, é nesse intervalo que a maioria das pessoas desiste.
| Situação | Ferramenta melhor | Por quê |
|---|---|---|
| Tarefa de configuração feita pela primeira vez | Tour de produto | Conduz pela interface real em vez de descrevê-la. |
| Um controle cuja finalidade não é clara | Tooltip | Responde à dúvida no lugar onde ela surge. |
| Uma sequência de primeiras conquistas | Checklist de onboarding | Acompanha o progresso; um documento não consegue. |
| Uma funcionalidade que ninguém descobriu | Hotspot | Ninguém lê um guia sobre uma funcionalidade que nem sabe que existe. |
| Uma tela vazia | Texto de estado vazio | A instrução pertence ao lugar onde está o vazio. |
| Referência aprofundada, casos extremos, configuração de admin | Um guia escrito | Profundidade, facilidade de busca e permanência são os verdadeiros pontos fortes da documentação. |
A divisão de trabalho honesta: a orientação dentro do produto cuida da primeira hora, e a documentação cuida de tudo o que vem depois. Equipes que tentam fazer os guias escritos carregarem o onboarding acabam com uma documentação completa e uma ativação fraca, e geralmente concluem que a documentação precisa ser mais longa.
Como manter os guias do usuário vivos
✅ Faça
- Dê às páginas o nome das tarefas, nas palavras do usuário
- Informe primeiro o resultado e os pré-requisitos
- Escreva enquanto executa a tarefa
- Mantenha uma ação por passo numerado
- Inclua um passo de verificação
- Mostre uma data de última atualização visível
- Garimpe os tickets de suporte em busca de guias que faltam
- Coloque links para o guia dentro do produto
❌ Não faça
- Espelhar o menu de navegação na estrutura da documentação
- Cobrir três tarefas em uma única página
- Fazer captura de tela de cada passo
- Esconder os pré-requisitos no meio do texto
- Explicar a arquitetura dentro de um guia de como fazer
- Publicar vídeo sem equivalente em texto
- Deixar guias sem responsável
- Esperar que a documentação faça o trabalho do onboarding
Deixe os dados dizerem o que escrever em seguida
Três sinais, em ordem de utilidade: as palavras exatas dos tickets de suporte que se repetem, as buscas na sua central de ajuda que não retornam nada e as páginas com muito tráfego e alta taxa de saída. O primeiro mostra o que está faltando, o segundo mostra o que as pessoas esperavam encontrar e o terceiro mostra qual guia existente está falhando.
Combine seus guias com orientação in-app
A configuração mais forte não é documentação ou ajuda dentro do produto; é documentação acessível de dentro do produto, no momento em que a dúvida surge, com o caminho de primeira vez conduzido de forma interativa.
- Transforme a tarefa de primeira vez em um tour. Converta seus três principais guias de primeiros passos em tours de produto interativos e compare as taxas de conclusão com as das versões escritas.
- Responda às pequenas dúvidas no lugar. Um tooltip em um campo confuso evita a busca que leva ao guia que leva a um ticket de suporte.
- Mostre o guia certo no contexto certo, em vez de mandar todo mundo para a página inicial da central de ajuda.
- Acompanhe qual orientação é realmente usada com analytics de produto e aposente o que ninguém abre.
- Anuncie as mudanças na documentação junto com as mudanças de funcionalidades, pelo widget de anúncios.
A Kompassify é uma plataforma de adoção digital no-code para equipes de SaaS: tours de produto, checklists, tooltips, anúncios, pesquisas in-app e analytics em um só lugar. Grátis até 100 usuários ativos mensais, planos pagos a partir de US$ 129/mês, em conformidade com o GDPR e com hospedagem na UE.
Transforme seu melhor guia em um walkthrough interativo
Pegue a página de primeiros passos que os usuários mais leem e execute-a dentro do seu produto: sem código, sem ticket para a engenharia.
Comece grátis →Perguntas frequentes
O que é um guia do usuário?
Um guia do usuário é um documento que ajuda alguém a concluir uma tarefa específica com um produto, escrito do ponto de vista do usuário e estruturado em torno do objetivo dele, e não da arquitetura do software. Em SaaS, ele costuma ficar em uma central de ajuda e funciona junto com a orientação dentro do produto, sem substituí-la. O que define um bom guia é ser organizado por tarefa, não pela estrutura dos menus.
Como escrever um guia do usuário?
Comece pela tarefa, nas palavras do próprio usuário, tiradas dos tickets de suporte e das buscas no site. Informe o resultado e os pré-requisitos antes do primeiro passo. Escreva os passos enquanto executa a tarefa de verdade no produto, e não de memória, com uma ação por passo numerado e o rótulo exato da interface em negrito. Inclua imagens apenas onde as palavras realmente não conseguem eliminar a ambiguidade. Termine com como confirmar que funcionou, o que costuma dar errado e a próxima tarefa natural. Depois, teste com alguém que nunca fez a tarefa.
Quais são os diferentes tipos de guia do usuário?
Vale a pena distinguir cinco: guias de como fazer, que respondem a 'como eu faço X' com passos numerados; guias de primeiros passos, que mostram o caminho mais curto até o primeiro valor; material de referência, que explica o que cada configuração faz e deve ser fácil de escanear em vez de escrito em prosa; guias conceituais, que explicam por que o produto funciona de determinado jeito; e conteúdo de solução de problemas organizado por sintoma. Misturar esses tipos na mesma página é a falha de documentação mais comum.
Qual deve ser o tamanho de um guia do usuário?
O tamanho que a tarefa exige, e nada além disso. Um guia de como fazer para uma única tarefa costuma ter de 300 a 800 palavras, com cinco a nove passos. Um guia de primeiros passos fica entre 500 e 1.200 palavras. Guias conceituais podem justificar de 800 a 2.000. Material de referência não tem um tamanho natural. A restrição importante não é a contagem de palavras, e sim o escopo: uma página deve cobrir um único resultado, porque uma página que cobre três tarefas não será encontrada por ninguém que procure qualquer uma delas.
Guias do usuário devem incluir capturas de tela?
Só onde as palavras não dão conta. Cada captura de tela é um custo de manutenção, e um guia cheio de imagens desatualizadas é pior do que um sem nenhuma, porque passa a informar errado depois de uma mudança na interface. Use uma imagem quando o alvo for difícil de descrever, quando o usuário precisar confirmar que está no lugar certo ou quando o próprio resultado for visual. Recorte bem e faça anotações, em vez de colar a janela inteira.
Quando a orientação in-app é melhor do que um guia do usuário escrito?
Em tarefas feitas pela primeira vez em uma interface desconhecida. Um guia escrito exige que o usuário saia do produto, encontre a página, guarde os passos na cabeça e volte, e é nesse intervalo que a maioria das pessoas desiste. Tours de produto, tooltips, checklists, hotspots e textos de estados vazios eliminam essa etapa de tradução. A documentação escrita continua sendo a melhor ferramenta para profundidade, referência, casos extremos e solução de problemas.
Como manter os guias do usuário atualizados?
Dê a cada guia um responsável nomeado e uma data de revisão, e mostre na página uma data de última atualização visível, para que o leitor saiba se pode confiar no conteúdo. Vincule a revisão da documentação ao seu processo de release, em vez de tratá-la como um projeto à parte. Depois, use três sinais para decidir o que corrigir primeiro: tickets de suporte repetidos, buscas na central de ajuda que não retornam nada e páginas com muito tráfego e alta taxa de saída.
Como decidir quais guias do usuário escrever em seguida?
Garimpe sua fila de suporte em busca das perguntas que se repetem e use as palavras exatas dos clientes como título da página. Depois, veja as buscas internas que não retornam resultados, que mostram o que as pessoas esperavam encontrar. As duas fontes são melhores do que adivinhar a partir de uma lista de funcionalidades, porque refletem o que os usuários estão de fato tentando fazer, e não o que o produto por acaso contém.