Como planejar um conjunto de documentação de software com capturas de tela

Um conjunto de documentação com capturas de tela é fácil de começar e difícil de manter. Cada imagem é uma cópia da interface em um dia específico, e a interface continua mudando. O planejamento feito antes das capturas determina se o conjunto sobrevive à primeira reformulação.

Este texto explica como estruturar o conjunto, definir regras para as capturas de tela e produzi-las em um Mac com o Temposhot. Um exemplo prático acompanha todas as seções: um pequeno aplicativo web de faturamento com cinco áreas de produto e um redator técnico que também atende o suporte.

Liste as perguntas que os leitores precisam responder

Reúna perguntas reais antes de decidir as páginas. Boas fontes são tickets de suporte, ligações comerciais, sessões de onboarding, conversas internas e os termos de busca da documentação atual.

Escreva cada pergunta com as palavras do leitor:

• "Como convido um membro da equipe?"
• "Por que minha exportação está em branco?"
• "O que significa o status de Sync?"
• "Qual plano inclui os registros de auditoria?"

Agrupe as perguntas duplicadas. A lista resultante define o escopo do conjunto. O que não estiver nela pode esperar.

Exemplo prático: dos tickets à lista de perguntas

A equipe de faturamento exportou 240 tickets de suporte dos últimos 90 dias. Ler apenas os assuntos e a primeira mensagem de cada cliente levou cerca de duas horas. Depois de unir as duplicatas, restaram 52 perguntas distintas.

Nove perguntas apareceram mais de dez vezes cada. Essas nove cobriam quase metade de todos os tickets, então definiram a ordem do trabalho. As outras 43 perguntas foram para um backlog organizado por área: faturas, clientes, pagamentos, configurações e cobrança.

Registre as palavras que os leitores usam

Mantenha a redação do leitor ao lado de cada pergunta, mesmo quando ela não coincide com o rótulo da interface. Um cliente que escreve "remover um cartão" não vai buscar por "Métodos de pagamento". O título da página deve usar o rótulo do produto, e a primeira frase pode repetir o termo do leitor para que a busca encontre os dois.

Registre também o contexto de cada pergunta: o plano, o papel e o dispositivo. "Como estorno uma fatura" feita por um proprietário de conta e a mesma pergunta feita por um usuário com papel de visualizador levam a páginas diferentes. Uma é um guia de tarefa, a outra é uma página de solução de problemas sobre permissões ausentes.

Remova perguntas que a documentação não resolve

Alguns tickets descrevem um bug ou uma funcionalidade ausente. Uma página que explica um bug vira um workaround que sobrevive à correção. No exemplo, 6 relatos de bug foram separados durante a união, antes da contagem de 52, e foram enviados à equipe de produto em vez do backlog de documentação.

Outras perguntas surgem de um rótulo confuso. Se dez leitores perguntam o que significa "Sync", uma página de referência ajuda, mas um rótulo mais claro ajuda mais. Envie essas perguntas também à equipe de produto e escreva a página apenas se o rótulo for mantido.

Atribua um tipo de página a cada pergunta

Perguntas diferentes exigem formatos de página diferentes. Misturá-los torna as páginas longas e difíceis de percorrer.

Tipo de página	Responde	Capturas de tela
Guia de tarefa	"Como faço X"	Uma por passo
Referência	"O que significa X"	Uma visão geral anotada por tela
Solução de problemas	"Por que X falhou"	O estado de erro e a correção
Conceito	"Como X funciona"	Diagramas, poucas capturas ou nenhuma

Marque cada pergunta da lista com um tipo. A maioria das perguntas sobre o produto vira guia de tarefa.

Conte as capturas de tela antes de escrever

O tipo de página indica quantas imagens cada uma vai conter. Multiplique esse número pela quantidade de páginas e obtenha o total de imagens que precisam de atualização após cada reformulação. Vale conhecer esse número antes de qualquer pessoa abrir a ferramenta de captura.

No exemplo, 31 das 52 perguntas viraram guias de tarefa, com média de 7 passos. Doze viraram páginas de solução de problemas com 2 imagens cada, 6 viraram páginas de referência com 1 visão geral anotada cada, e 3 viraram páginas de conceito sem capturas de tela.

As 247 imagens são a carga real de manutenção do conjunto. Uma reformulação de uma área de produto que afete um quinto delas significa cerca de 50 substituições, o que equivale a um ou dois dias de trabalho. Saber esse número torna a política de capturas de tela descrita a seguir mais fácil de justificar.

Separe perguntas que misturam tipos

Algumas perguntas combinam dois tipos. "Por que minha exportação está em branco e como corrijo" é uma página de solução de problemas que leva a um guia de tarefa. Escreva a página de solução com o erro e a causa, e depois aponte para o guia de tarefa com o procedimento completo.

Defina uma política de capturas de tela

Defina uma vez como as capturas de tela devem ser e registre essa definição por escrito. Um conjunto consistente parece mantido e é mais rápido de atualizar.

• Tamanho da janela: um tamanho fixo para todas as capturas. O alvo Specific Window do Action Capture mantém a mesma janela durante toda a execução.
• Tema e idioma: claro ou escuro, e um único idioma de interface.
• Dados: somente contas de exemplo e nomes fictícios.
• Recorte: a janela ou o painel, nunca a área de trabalho inteira. Use Framing com Focus on action em Balanced ou Close.
• Marcações: um marcador de clique ou uma seta por imagem, com uma cor de destaque.
• Formato: PNG para textos da interface, WebP se o site precisar de arquivos menores.

Defina também quando não há necessidade de capturas de tela: uma configuração de um único campo, um passo cujo rótulo já está no texto, uma tela que muda a cada versão.

Transforme a política em configurações de captura

Uma política escrita só funciona quando as configurações de captura correspondem a ela. Configure o Action Capture uma vez, e os valores ficam salvos no Mac para todas as execuções seguintes. A equipe do exemplo usou as configurações abaixo nas 31 guias de tarefa.

Specific Window mantém uma janela do navegador como alvo durante toda a execução, então cada passo tem a mesma largura em pixels. Desative Include toolbar in captures, caso contrário a barra de ferramentas flutuante aparece nas imagens da documentação. Mantenha Capture outside clicks desativado, a menos que a tarefa use uma segunda janela, como um gerenciador de senhas.

Defina os níveis de enquadramento por tipo de página

O enquadramento não altera a imagem original, então a política pode indicar um nível e ainda assim prever exceções. As guias de tarefa usaram Balanced (nível 3) por padrão, o que mantém parte suficiente da página para o leitor encontrar o controle. Controles pequenos, como um interruptor em uma lista longa de configurações, passaram para Close (nível 4).

As visões gerais de referência não usaram enquadramento. Elas mostram a janela inteira com rótulos numerados, porque o objetivo é nomear cada região. Step Numbers é uma ferramenta do plano Pro, então, no plano gratuito, o mesmo resultado exige rótulos Text posicionados manualmente.

Defina quando não capturar

Cada imagem é uma atualização futura, então a política também deve listar os casos em que não há captura de tela. A equipe do exemplo dispensou imagens para passos cuja única ação era digitar um valor em um campo com rótulo. Também dispensou as notificações de confirmação que desaparecem em 3 segundos e descreveu a mensagem em texto.

Se nenhum dos cinco pontos se aplicar, escreva o passo apenas em texto. No exemplo, essa regra removeu 38 das 217 imagens planejadas para as guias de tarefa antes do início das capturas.

Prepare uma conta de exemplo para cada captura

Capturas feitas com contas diferentes mostram nomes, totais e datas diferentes, e os leitores percebem. A equipe do exemplo criou um workspace de exemplo com 3 clientes, 12 faturas e 2 métodos de pagamento, todos com nomes fictícios. Cada guia parte desse workspace, então o mesmo nome de cliente aparece em todas as páginas.

Restaure os dados de exemplo antes de cada execução. Um guia gravado depois de outro guia ter excluído uma fatura vai mostrar 11 faturas em vez de 12, e a próxima atualização não vai coincidir. Escreva os passos de restauração no início do documento da política para que outro redator consiga repeti-los.

Defina o tamanho da janela do navegador antes de cada execução e não o altere. O Temposhot captura a janela no tamanho atual; ele não redimensiona janelas. Uma observação na política, como "janela do navegador com 1440 pontos de largura, zoom em 100 por cento", garante que capturas feitas em dias diferentes tenham a mesma escala.

Nomeie e armazene as imagens para substituição

Toda imagem será substituída em algum momento. Nomeie os arquivos de modo que você encontre rapidamente todas as imagens de uma mesma tela.

Um padrão como area-tarefa-passo.png, por exemplo billing-change-plan-03.png, ordena as imagens por área e tarefa. Mantenha uma pasta por guia e armazene o Document do Temposhot de cada guia para poder exportá-lo novamente após as edições.

As exportações de imagem do Temposhot usam os títulos das páginas nos nomes dos arquivos. Defina os títulos antes da exportação ou renomeie os arquivos no repositório de documentação depois. O pacote ZIP adiciona um document.json junto às páginas PNG renderizadas, o que ajuda se você automatizar a importação para um sistema de documentação.

Estrutura de pastas do conjunto do exemplo

Uma pasta por área de produto contém uma pasta por guia. As imagens exportadas ficam ao lado da página que as usa, então um pull request que altera um guia também mostra quais imagens mudaram.

Mantenha os títulos das páginas e os nomes dos arquivos sincronizados

Como o Temposhot nomeia os arquivos de imagem a partir dos títulos das páginas, um título como Click "Change plan" gera um nome de arquivo difícil de ordenar. Há duas soluções viáveis. Reescreva os títulos com o texto final voltado ao leitor e renomeie os arquivos no repositório com um script, ou exporte um pacote ZIP e use a ordem das páginas em document.json para nomear os arquivos.

Qualquer que seja a opção escolhida pela equipe, o número do passo no nome do arquivo deve corresponder ao número do passo na página. Quando o passo 4 for excluído, renumere os arquivos seguintes no mesmo commit.

Armazene os Documents de origem

Cada imagem exportada vem de um Document no Mac que a registrou. Os Documents ficam na biblioteca de Documents (Command+4) desse Mac, e o Temposhot não os sincroniza. Dê a cada Document exatamente o nome da pasta do guia, por exemplo billing-change-plan, para que a origem de qualquer imagem possa ser encontrada pela busca na biblioteca.

Crie guias de tarefa antes de tours amplos

Os guias de tarefa respondem às perguntas mais comuns e são os mais fáceis de verificar. Escreva-os primeiro.

1. Abra o Action Capture

   Pressione Command+3, selecione Start Action Capture e escolha Specific Window.

2. Execute a tarefa

   Percorra a tarefa uma vez. Cada clique aceito salva a janela logo antes do clique, com um título provisório gerado por Parse clicked elements.

3. Finalize e edite

   Selecione Finish capture. No editor, reescreva os títulos, enquadre as páginas e adicione marcações.

4. Exporte as páginas

   Abra More export formats e escolha páginas PNG ou WebP para o site de documentação.

Tours de produto e páginas de visão geral vêm depois, quando os guias de tarefa mostrarem quais telas são mais importantes. O guia do Action Capture e o guia de exportação de Documents detalham o processo.

Ordene o primeiro lote pelo volume de tickets

A equipe do exemplo capturou as nove perguntas mais frequentes na primeira semana. Cada guia levou cerca de 25 minutos: 5 minutos para restaurar a conta de exemplo, 5 minutos para gravar e 15 minutos para editar títulos, enquadramento e marcações. Os nove guias levaram cerca de quatro horas no total.

Reescreva os títulos provisórios como instruções

Parse clicked elements preenche o título de cada página com o nome do controle, como Click "Change plan". Cliques em controles sem nome legível recebem Click here. Ambos são provisórios. Um título voltado ao leitor começa com um verbo, nomeia o controle em negrito e acrescenta o resultado quando ele não é óbvio.

Título provisório	Título reescrito
Click "Billing"	Abra Billing na barra lateral
Click here	Selecione o card do plano Team
Click "Confirm"	Selecione Confirm para trocar de plano na próxima renovação

O título reescrito também se torna o nome do arquivo de imagem na exportação, então um título claro ajuda tanto o leitor quanto o repositório.

Confira o número de passos contra o limite do plano gratuito

O plano gratuito pausa uma execução do Action Capture após 5 passos, e os passos já capturados permanecem salvos. Guias de sete passos, como os do exemplo, exigem o Temposhot Pro ou duas execuções adicionadas a um mesmo Document. Para adicionar a segunda execução, use Capture new images… no painel Pages, que acrescenta os novos quadros ao Document aberto.

Edite as páginas com atalhos de teclado

A edição é onde se gasta a maior parte dos 25 minutos por guia. As teclas do editor abaixo cobrem as edições mais comuns nas páginas de documentação.

As anotações são não destrutivas. Um retângulo adicionado nesta versão pode ser movido ou excluído após a próxima reformulação, sem nova captura do passo, desde que a tela de origem continue igual.

Conecte o conjunto de documentação

Os leitores raramente chegam à página de que precisam. Crie links entre as páginas para que possam ir de um conceito até a tarefa, e de um erro até a correção.

• Cada guia de tarefa leva aos seus pré-requisitos e à próxima tarefa provável.
• Cada página de solução de problemas leva ao guia de tarefa que resolve o problema.
• Cada página de referência leva às tarefas que usam a tela.

Uma página de índice curta por área de produto, listando as tarefas por objetivo, ajuda os leitores que navegam em vez de pesquisar.

Padrão de links a partir de uma pergunta

A pergunta "Por que minha exportação está em branco" no exemplo gerou uma cadeia de quatro páginas. Um leitor que chega a qualquer uma delas consegue ir às outras três com um clique.

Evite páginas órfãs

Depois da publicação, liste todas as páginas e conte os links de entrada. Uma página sem link de entrada só é encontrada pela busca. No exemplo, 4 das 52 páginas não tinham nenhum, e cada uma foi incluída no índice da sua área.

Defina responsáveis e gatilhos de revisão

Atribua um responsável a cada página, normalmente a equipe que é dona do recurso. Registre a versão do produto à qual as capturas de tela correspondem.

Gatilhos de revisão funcionam melhor do que lembretes apenas por calendário:

• Uma versão altera uma tela presente no conjunto.
• Um rótulo ou item de menu é renomeado.
• O suporte relata um passo que não corresponde mais à interface.
• Um intervalo fixo passa, como um trimestre, sem outro gatilho.

O post sobre como manter a documentação com capturas de tela atualizada descreve a rotina de atualização.

Substitua as imagens após uma versão

Quando uma versão altera uma tela, os nomes dos arquivos permitem localizar rapidamente as imagens afetadas. Pesquise no repositório pelo prefixo da área, abra os Documents correspondentes e execute novamente apenas os passos que mudaram.

Novas páginas de uma captura podem ser inseridas após a página selecionada. Selecione a página anterior ao passo alterado, execute a captura, e a nova página será colocada na posição correta.

Divida a responsabilidade por área de produto

Um único redator não consegue revisar 52 páginas após cada versão. A equipe do exemplo atribuiu cada área ao engenheiro responsável por ela, com o redator como editor. O responsável sinaliza as telas alteradas no ticket da versão, e o redator substitui as imagens.

Registre a versão do produto em cada página

Adicione a versão do produto aos metadados da página ou à última linha, por exemplo "Capturas de tela correspondem à versão 4.2". Quando o suporte relatar uma divergência, a versão indica quanto a página está defasada. Páginas com mais de duas versões de atraso vão para o topo da fila de revisão.

Perguntas frequentes

Quantas capturas de tela uma página de documentação de software deve ter?

Uma por passo nas guias de tarefa, e o menor número possível nos demais casos. Cada imagem é uma atualização futura, então adicione uma somente quando ela reduzir o esforço do leitor.

As capturas de tela da documentação devem mostrar a tela inteira?

Raramente. Recorte a janela ou o painel. Imagens em tela cheia mostram aplicativos não relacionados e reduzem o tamanho do texto da interface.

O que é documentação visual?

Documentação que usa capturas de tela, diagramas ou vídeos junto com o texto. Veja documentação visual no glossário.

Qual formato de imagem um site de documentação deve usar?

Páginas PNG mantêm o texto da interface nítido. Páginas WebP geram arquivos menores e aparecem em More export formats somente quando um codificador WebP está disponível no Mac. O Image Compressor pode reduzir ainda mais os arquivos PNG antes do upload.

Quanto tempo leva a atualização das capturas de tela após uma reformulação?

Depende de quantas imagens mostram as telas alteradas. No exemplo, uma reformulação de uma área afetou cerca de 50 das 247 imagens. Executar novamente apenas os passos alterados a partir dos Documents salvos levou de um a dois dias, contra cerca de uma semana para refazer os mesmos guias do zero.

Vários redatores podem compartilhar um mesmo Document do Temposhot?

Não. Os Documents ficam armazenados no Mac que os criou. Compartilhe os arquivos exportados pelo repositório de documentação e mantenha o Document de origem de cada guia no Mac do responsável.

Transforme seus cliques em um guia passo a passo claro

O Action Capture registra cada guia de tarefa em uma única passagem, com tamanho de janela consistente e títulos provisórios. Baixe o Temposhot e comece pela pergunta mais frequente da sua lista.