Como escrever instruções passo a passo claras para software

Instruções claras de software permitem que o leitor conclua a tarefa sem precisar pensar nas próprias instruções. Cada palavra extra, rótulo vago ou passo combinado obriga o leitor a parar e reler.

Este post reúne as regras de escrita mais importantes, com exemplos, e mostra como aplicá-las ao criar um guia no Temposhot em um Mac.

Defina um resultado final

Escreva o resultado primeiro, em uma frase que o leitor possa verificar: "A fatura é enviada ao cliente e marcada como Enviada." Essa frase vira o título e o último passo.

Se você não consegue escrever um único resultado, as instruções cobrem mais de uma tarefa. Separe-as. Quem pesquisa "enviar uma fatura" não quer rolar a página até encontrar "criar um cliente".

Escreva o resultado antes da primeira captura de tela. Um resultado escrito depois da captura tende a descrever a gravação, com todos os cliques que o autor fez por acaso. Um resultado escrito primeiro define quais cliques pertencem ao guia. Cliques que apenas levam a outra tela, como abrir um menu para chegar à página certa, geralmente podem ser substituídos por um único rótulo que nomeia o destino.

Quando uma tarefa envolve dois papéis, escreva dois guias com um resultado cada. Um guia para quem aprova a fatura e outro para quem a envia têm pontos de partida e verificações diferentes. Juntá-los obriga cada leitor a pular as partes que não se aplicam ao seu papel.

Um resultado vago e um resultado verificável

Um resultado é verificável quando o leitor olha para a tela e consegue responder sim ou não. A comparação abaixo mostra a mesma tarefa escrita de duas formas.

A versão verificável também define o tamanho do guia. Um guia que termina com um status visível tem um último passo natural, então o autor não precisa acrescentar um parágrafo de encerramento que repete o primeiro.

Comece cada passo com a ação

O leitor procura o verbo. Coloque-o no início.

Fraco	Claro
O menu Settings agora deveria ser aberto.	Abra Settings.
Em seguida, você vai querer clicar em Save.	Selecione Save.
No canto superior direito há um botão Share.	Selecione Share no canto superior direito.
Certifique-se de que as notificações estão desativadas.	Desative Notifications.

Mantenha uma lista curta de verbos e use-a de forma consistente: Abra, Selecione, Escolha, Digite, Ative, Desative, Arraste. "Clicar" funciona para usuários de mouse, mas não serve para quem usa teclado ou toque, por isso muitos guias de estilo preferem "Selecione".

Use o modo imperativo em todos os passos. "Selecione Save" e "Abra Settings" dizem ao leitor o que fazer agora. "Você deve selecionar Save" acrescenta uma camada que o leitor precisa remover antes de agir. A mesma regra vale para a frase de resultado no fim de um passo, que descreve o que a tela mostra: "O banner mostra Changes saved."

Um verbo para cada tipo de controle

Uma lista de verbos só funciona quando cada verbo corresponde a um tipo de controle. Um leitor que vê "Escolha" espera uma lista ou um menu, e um leitor que vê "Selecione" espera um botão ou um link. A lista abaixo define uma regra para cada verbo.

Quando um controle não corresponde a nenhum verbo da lista, descreva a localização e o rótulo dele. Um controle que abre um seletor usa "Escolha", e um controle que inicia um processo usa "Selecione". Mantenha a lista curta, porque cada verbo novo é mais uma regra que o autor precisa lembrar.

Use rótulos exatos da interface

Copie os rótulos exatamente como a interface os mostra, incluindo maiúsculas e pontuação. Se o botão diz Add member, não escreva "Adicione um usuário". O leitor procura as palavras que estão na tela.

Deixe o rótulo em negrito para que ele se destaque na frase. Indique a localização apenas quando o rótulo é difícil de encontrar ou aparece duas vezes: "Selecione Export na barra de ferramentas, e não no menu File."

Rótulos que aparecem duas vezes

Um rótulo que aparece em dois lugares leva o leitor ao controle errado quando o passo menciona só o rótulo. Uma caixa de diálogo costuma repetir o botão da barra de ferramentas com a mesma palavra, então um passo que diz apenas "Selecione Export" pode ser lido de duas formas. A solução é nomear o lugar que o passo quer dizer e informar o que o leitor deve ver em seguida. "Selecione Export na barra de ferramentas. A caixa de diálogo de exportação abre." A segunda frase confirma que o leitor está no controle certo antes de continuar.

Menus criam um segundo problema. Um item de menu chamado Settings pode existir no menu do app e na barra da janela. Escreva o caminho apenas quando o leitor precisar dele, e escreva-o uma vez, no passo que usa o menu pela primeira vez.

Regras de rótulo para a busca do leitor

Um leitor que não encontra um rótulo costuma procurar o texto exato na tela. Uma paráfrase o leva ao lugar errado ou a lugar nenhum. A tabela abaixo mostra as regras na prática.

Um rótulo que muda entre versões do app precisa de uma nota. Informe a versão na descrição da página, por exemplo "Na versão 4, o botão diz Invite." A nota responde à dúvida antes que o leitor a faça.

Mantenha uma decisão por passo

Um passo deve conter uma ação ou uma escolha. "Abra Settings, selecione Billing e altere o plano" são três passos. Quando o leitor volta a olhar para a tela, ele perde o ponto em que estava dentro de uma frase longa.

Exceção: duas ações na mesma área pequena que sempre acontecem juntas, como "Digite o código e selecione Verify". Mesmo assim, separe-as se a segunda ação depender de uma condição.

Passos de decisão exigem o mesmo cuidado. Quando o leitor precisa escolher entre opções, liste as opções no passo ou informe a configuração que controla a escolha. "Escolha um formato" deixa o leitor adivinhar as opções. "Escolha PDF ou PNG em Format. Escolha PDF para impressão" dá uma regra que o leitor aplica sem reler.

Divida um passo composto

Um passo composto costuma esconder um ponto de decisão. O exemplo abaixo parte de um passo que altera uma assinatura e o divide em cada ação que o leitor precisa confirmar.

A primeira versão da frase tinha seis verbos e uma confirmação. Os quatro passos acima têm uma ação cada, e o último passo contém um ponto de verificação, tema da próxima seção.

Adicione pontos de verificação após ações importantes

Depois de uma ação que altera algo, informe o que o leitor deve ver: "Um banner verde mostra Changes saved." Os pontos de verificação confirmam o progresso e identificam erros cedo, antes que o leitor avance cinco passos.

Coloque pontos de verificação depois de salvamentos, envios, importações, pedidos de permissão e qualquer coisa que demore para carregar.

Desvios de erro

Um ponto de verificação informa como é o sucesso. Um desvio de erro informa como é a falha e para onde ir em seguida. Escreva um desvio para cada ponto de verificação que pode falhar. O desvio nomeia a mensagem visível, a ação a tomar e o passo para o qual retornar.

Considere um passo de upload. O ponto de verificação de sucesso diz "O nome do arquivo aparece na lista." O desvio de erro diz: "Se a lista mostrar Upload failed, selecione Try again. Se falhar de novo, acesse a página de solução de problemas sobre limites de tamanho de arquivo." O leitor vê a mensagem, sabe a ação e sabe quando parar.

Mantenha os desvios de erro curtos. Um desvio com três ramificações pertence a um guia de solução de problemas separado, vinculado a partir do passo. Um desvio que precisa de mais de uma tela para ser explicado geralmente são duas tarefas.

Onde os pontos de verificação ficam em um guia longo

Um guia sem pontos de verificação falha tarde, depois que o leitor já fez várias alterações que agora precisa desfazer. Os números abaixo descrevem um guia de exemplo de 12 passos, com os pontos de verificação posicionados onde a próxima ação do leitor depende de um resultado.

Um ponto de verificação que descreve um resultado visível é mais útil do que um que diz "Concluído". "Concluído" não confirma nada na tela. "A linha mostra Imported com 240 registros" dá ao leitor um número para comparar com a própria tela.

Escreva ramificações a partir de condições observáveis

As ramificações são onde os leitores se perdem. Baseie-as em algo que o leitor consegue ver, e não em algo que ele precisa saber.

• Fraco: "Se você estiver no plano legado, ..."
• Claro: "Se a página mostrar Upgrade to continue, vá para o passo 7."

Mantenha as ramificações curtas. Se uma ramificação tiver mais de dois passos, mova-a para um guia próprio e vincule-o.

Evite ramificações que dependem do histórico do leitor. "Se você se cadastrou antes de 2025" pede que o leitor se lembre de algo que a tela não mostra. Substitua por um resultado visível: "Se a página da conta mostrar o selo Legacy, vá para o passo 7." Uma ramificação baseada na tela funciona para um leitor novo, para um leitor recorrente e para um agente de suporte que consulta o guia para outra pessoa.

Uma ramificação que começa em uma tela

O fluxo abaixo mostra uma ramificação que o leitor pode verificar na tela. Ele não precisa saber qual plano tem.

A ramificação devolve o leitor a um ponto conhecido. O passo 9 encerra o guia para os leitores que não podem exportar, e os demais não precisam pular essa parte.

Use capturas de tela para mostrar local e estado

O texto diz o que fazer. A captura de tela mostra onde fica e como está. Use uma por passo, recortada na área que importa, com uma marcação no alvo. A captura também confirma o estado: o leitor compara a própria tela e sabe que está no caminho certo.

O Temposhot cria essa dupla a partir dos seus cliques. Abra Action Capture (Command+3), ative Parse clicked elements em Configure e selecione Start Action Capture. Cada clique aceito salva a tela logo antes do clique, com um título de rascunho como Click "[[element-name]]". Depois de Finish capture, o Document abre no editor.

Recorte cada captura na janela ou no controle que o passo nomeia. Uma tela inteira mostra muitos controles, e o leitor precisa encontrar o que o passo nomeia. Antes de exportar, verifique se o recorte não mostra dados privados, como o nome de uma conta ou uma notificação não relacionada, e confira a imagem no tamanho em que ela será impressa ou exibida.

Reescreva cada título de rascunho com as regras acima, por exemplo Click "Save" para "Selecione Save para manter as alterações". Coloque os pontos de verificação e as condições na Page description. Na exportação em PDF, as descrições podem aparecer antes ou depois de cada captura (personalização disponível no Pro). O guia do editor cobre títulos, descrições e ferramentas.

Configurações para um guia de instruções

As configurações abaixo geram uma página por clique, com um alvo visível. Elas correspondem a um guia escrito para um leitor que usa uma única janela.

Use o atalho manual para uma tela que muda sem clique, como um status que se atualiza após o processamento. Ative Show cursor in shortcut captures nesses passos, para que o ponteiro marque o campo que o leitor precisa ler.

Mantenha o mesmo alvo de captura em todo o guia. Trocar de Active Window para Specific Window no meio do guia torna o enquadramento das páginas inconsistente.

Atalhos do editor para escrever páginas de passos

A maior parte das edições acontece no editor, uma página por vez. Os atalhos abaixo cobrem as ações mais usadas ao escrever títulos, descrições e marcações.

Remova palavras de preenchimento e suposições ocultas

Corte as palavras que não mudam o que o leitor faz:

• "Simplesmente", "apenas", "facilmente": não acrescentam nada e fazem o leitor que tem dificuldade se sentir pior.
• "Agora você vai querer", "Vá em frente e": comece pelo verbo.
• "Como mencionado acima": repita o fato ou vincule a ele.

Depois, procure suposições. O leitor sabe onde fica o app, qual conta usar, o que significa um termo? Acrescente uma linha para cada lacuna, geralmente nos pré-requisitos.

Meça o corte

O preenchimento é fácil de acrescentar e fácil de deixar passar. Contar as palavras antes e depois de uma edição mostra quanto uma única revisão remove.

O corte faz mais do que encurtar a página. Cada expressão removida era um ponto em que o leitor parava para decidir se ela importava. O passo editado se lê como instrução já na primeira leitura.

Teste as instruções sem explicá-las

Entregue as instruções a alguém que ainda não fez a tarefa. Observe a pessoa seguir o guia e não responda às perguntas. Cada pausa ou pergunta aponta para um passo que precisa de uma ação, um rótulo ou um ponto de verificação mais claro.

Escolha testadores que correspondam aos leitores. Um testador que construiu o produto conhece os rótulos e o fluxo, então uma execução limpa por essa pessoa prova pouco. Um testador da equipe de suporte ou um novo contratado no papel-alvo encontra as lacunas que o autor já deixou de ver. Entregue ao testador o guia e a conta que ele vai usar, e nada além disso.

Corrija esses passos e teste de novo com outra pessoa, se possível. Duas execuções limpas são um bom sinal de que as instruções funcionam. O checklist de tutorial com capturas de tela lista as verificações restantes antes da publicação.

Conduza uma sessão com anotações

Anote o horário e o número do passo de cada pausa, e deixe a explicação para depois da sessão. A linha do tempo abaixo mostra uma sessão em um guia de nove passos com uma descoberta útil.

As anotações mostram quais passos precisam de rótulos e quais precisam de um ponto de verificação. Uma única sessão mostra um padrão, não uma taxa, então faça uma segunda sessão antes de alterar o guia de novo.

Arquivos mantidos com um guia de instruções

Um guia tem mais arquivos do que páginas. O Document de origem fica na biblioteca de Documents, e o PDF exportado e as anotações ficam em uma pasta fora do app. A pasta mantém o número da versão e as anotações de teste ao lado do arquivo que os leitores recebem, para que a próxima edição parta do mesmo registro.

Perguntas frequentes

Devo usar "click" ou "select" nas instruções?

"Select" funciona para mouse, teclado e toque. Use "click" apenas se o seu público usa mouse e o seu guia de estilo prefere esse termo. Qualquer que seja a escolha, use-a de forma consistente.

Quanto deve ter cada passo?

Uma frase para a ação, mais uma frase opcional para o resultado ou a condição. Explicações mais longas pertencem a uma nota ou a uma página separada.

As instruções precisam de passos numerados?

Sim, quando a ordem importa. Os números permitem que o leitor mantenha o ponto em que está e que o suporte se refira ao "passo 4". A exportação em PDF do Temposhot pode adicionar números de passo (recurso do Pro).

Onde ficam os avisos?

Antes do passo a que se aplicam. Um aviso depois de uma ação destrutiva chega tarde demais.

Quantas capturas de tela um guia precisa?

Uma para cada passo em que a tela muda ou em que o alvo é difícil de encontrar. Um passo que apenas digita texto em um campo já visível não precisa de captura. Conte as capturas em relação aos passos depois do primeiro rascunho e remova qualquer uma que repita a mesma tela.

E se a interface mudar depois da publicação?

Encontre todos os passos que citam um rótulo ou uma localização alterada, e atualize a captura de tela e o título juntos. Uma captura nova com um rótulo antigo confunde o leitor mais do que a captura antiga. Registre a versão do app na descrição da página ou no rodapé do guia, para que os leitores saibam a qual versão o guia se refere.

Como escrevo para leitores que usam apenas o teclado?

Informe a tecla ou o alvo de foco quando o passo depender dela, por exemplo "Pressione Tab até que o botão Export receba o foco". Não conte com a palavra "clique" nem com a posição de um controle na tela, porque um leitor que usa teclado não enxerga a posição da mesma forma. Teste uma execução usando apenas o teclado antes de publicar.

Quantos pontos de verificação são suficientes?

Um após cada ação que salva, envia, importa ou altera o acesso, e um após qualquer passo que leve mais de alguns segundos. Pontos de verificação em excesso atrasam o leitor, então combine os pontos de duas ações que sempre acontecem juntas.

Transforme seus cliques em um guia passo a passo claro

O Action Capture gera uma captura de tela e um título de rascunho por clique, prontos para estas regras de escrita. Baixe o Temposhot e escreva seu próximo guia sobre uma gravação.