Como manter a documentação com capturas de tela atualizada

A documentação com capturas de tela fica desatualizada a cada versão do produto. Um botão renomeado, um menu movido ou um novo tema fazem o guia parecer errado, mesmo quando as etapas ainda funcionam, e os leitores deixam de confiar nele.

Este post descreve uma rotina de manutenção: quem é responsável por cada guia, o que dispara uma revisão e como substituir apenas as páginas alteradas usando o Temposhot no Mac.

A rotina é mostrada em um exemplo prático ao longo do texto. Um guia do administrador de 40 páginas cobre um produto web que lança uma versão a cada 6 semanas. A versão 4.3 renomeia um botão, adiciona um campo a uma caixa de diálogo e move um item da barra lateral. O guia precisa refletir essas mudanças antes da data de lançamento.

Defina um responsável e a versão verificada

Cada guia precisa de um responsável nomeado. Normalmente é a pessoa ou a equipe que responde pelo recurso mostrado no guia. Responsabilidade compartilhada costuma significar que ninguém atualiza o guia.

Registre, na capa ou na primeira página:

• Responsável: nome da pessoa ou da equipe.
• Versão verificada: versão do produto ou data de lançamento com a qual as capturas correspondem.
• Última verificação: data em que alguém seguiu o guia do início ao fim.

"Verificado" significa que alguém executou a tarefa seguindo o guia. Não significa apenas que alguém olhou para ele.

Coloque o registro onde o leitor o vê

A versão verificada deve estar no próprio guia, e não apenas em uma planilha de acompanhamento. Um leitor na versão 4.1 que abre um guia marcado como 4.3 entende de imediato por que uma tela parece diferente. A equipe de suporte pode pedir a versão antes de investigar uma divergência.

No Temposhot, a primeira página do Document pode conter o registro em Page title e Description. Uma exportação de PDF com Cover page ativado começa com o título do documento e o número de etapas. Assim, um título como "Guia do administrador, verificado na versão 4.3" mostra a versão na capa. Alterar as configurações da capa faz parte da personalização do PDF, que exige o Temposhot Pro. As configurações padrão já incluem a página de capa.

Divida um guia longo por responsável

O guia do administrador de 40 páginas do exemplo cobre membros, funções, faturamento e logs de auditoria. Quatro áreas normalmente significam quatro responsáveis. Um responsável por seção funciona melhor do que um único responsável para 40 páginas, porque a equipe de faturamento percebe as mudanças no faturamento primeiro.

Um responsável de seção aprova somente as próprias páginas. O responsável pelo guia reúne essas aprovações e altera a versão verificada quando as quatro estiverem concluídas.

Use mudanças no produto como gatilhos de revisão

Revisões apenas por calendário detectam problemas tarde. Vincule as revisões a eventos que alteram telas:

Gatilho	Quem percebe	Ação
As notas de versão mencionam uma tela presente em um guia	Responsável pela documentação	Verificar os guias afetados antes do lançamento
Um rótulo ou item de menu é renomeado	Produto ou design	Pesquisar nos guias pelo rótulo antigo
Redesenho de tema ou de layout	Design	Planejar uma recaptura completa
O suporte relata uma divergência	Suporte	Corrigir até a próxima semana útil
Nenhum gatilho durante um trimestre	Responsável pela documentação	Conferir por amostragem os guias mais usados

Peça à equipe de produto que marque os itens de versão que alteram a interface visível. Esse hábito único torna a maioria dos gatilhos automática.

Encaixe a revisão em um ciclo de lançamento de 6 semanas

Com um lançamento a cada 6 semanas, o trabalho de documentação tem um horário fixo. A interface é congelada em uma build de staging alguns dias antes do lançamento, e capturas feitas antes podem continuar mudando. Capturar na build congelada e exportar antes da data de lançamento mantém o guia alinhado ao produto.

Capturar cedo demais é o erro mais comum neste ciclo. Um rótulo que muda de novo depois do congelamento exige uma segunda recaptura das mesmas páginas.

Use uma conta de staging com dados estáveis

Recapture em uma conta cujos dados não mudem entre as versões. Os mesmos três membros de teste, os mesmos números de fatura e o mesmo nome de plano mantêm as novas capturas consistentes com as páginas que não mudaram. Uma página capturada com outros dados de exemplo destoa das antigas, mesmo quando a interface é idêntica.

Trate uma divergência relatada pelo suporte

O suporte costuma encontrar mudanças que as notas de versão não listaram. Um chamado que diz "o guia mostra um botão que não encontro" precisa de três informações antes de qualquer recaptura: o nome do guia, o número da página e a versão do produto que o cliente usa. Sem a versão, um cliente na 4.1 pode disparar uma atualização de um guia que já está correto para a 4.3.

Forneça à equipe de suporte um modelo curto com esses três campos. Uma divergência confirmada na versão atual entra na próxima semana útil. Uma divergência em uma versão anterior vai para a questão de arquivamento descrita abaixo.

Mapeie a mudança para as etapas afetadas

Antes de recapturar, descubra exatamente quais páginas mostram a tela alterada. Um inventário torna isso rápido:

Guia	Telas exibidas	Versão verificada	Responsável
Convidar um integrante	Members, caixa de diálogo Invite	4.2	Administração de equipes
Exportar faturas	Billing, lista de Invoices	4.1	Financeiro

Quando uma versão altera a caixa de diálogo Invite, o inventário mostra o guia e as páginas a verificar. Sem ele, alguém precisa abrir todos os guias.

Exemplo prático: versão 4.3

A versão 4.3 traz três mudanças visíveis. O botão Add member na página Members é renomeado para Invite. A caixa de diálogo Invite ganha um campo novo, Role. O item Invoices sai do menu da conta e passa para a barra lateral de Billing.

O inventário associa essas mudanças a 7 das 40 páginas:

Mudança na 4.3	Páginas que mostram a mudança	Método de recaptura
Add member renomeado para Invite	6 (lista de Members), 14 (tela de resumo)	Action Capture da página Members
Campo Role na caixa de diálogo Invite	7, 8, 9 (caixa de diálogo Invite, escolha de função, confirmação)	Action Capture do fluxo de convite
Invoices movido para a barra lateral de Billing	27, 28 (navegação e lista de faturas)	Action Capture do caminho de faturamento

As outras 33 páginas permanecem como estão. As capturas delas ainda correspondem à 4.3, então recapturá-las acrescentaria trabalho sem alterar o que o leitor vê.

Encontre diferenças visuais com Compare Images

As notas de versão não listam cada alteração de pixel. Uma mudança de espaçamento, um ícone novo ou um botão com outra cor podem passar despercebidos. Para páginas que as notas não mencionam, faça uma captura nova da mesma tela e compare-a com a imagem exportada da página.

Compare Images mostra duas versões com um controle deslizante, uma transição de fusão, lado a lado ou como visualização de diferença pixel a pixel. A visualização de diferença destaca as regiões alteradas, o que facilita localizar um controle movido. A ferramenta roda no navegador e serve como verificação rápida das 33 páginas que o inventário marcou como inalteradas.

Substitua somente as etapas afetadas

Recapturar um guia inteiro por causa de uma caixa de diálogo alterada desperdiça tempo e aumenta o risco de novos erros. Substitua apenas as páginas que mudaram.

1. Abra o Document

   Pressione Command+4 e abra o Document do guia.

2. Capture as novas telas

   Abra o menu de adicionar no painel Pages, escolha Capture new images… e, em seguida, Action Capture. Execute apenas as etapas alteradas e selecione Finish capture. As novas páginas voltam ao editor e podem ser inseridas após a página atual.

3. Mova e remova

   Arraste as novas páginas para o lugar certo no painel Pages, ou use Move up e Move down. Use Delete page nas páginas desatualizadas.

4. Transfira títulos e marcações

   Copie os títulos e as descrições das páginas antigas antes de excluí-las. Copie as anotações com Command+C e Command+V e, depois, ajuste a posição delas.

5. Exporte novamente

   Selecione Export PDF ou use More export formats. As exportações refletem a ordem atual das páginas, o enquadramento e as anotações.

O guia de páginas e importações explica como adicionar páginas a partir de capturas, imagens e Capture History.

Execute Action Capture de novo ou adicione pelo Capture History

Há duas formas de incluir novas páginas no Document. Capture new images… executa uma captura dentro do Document e adiciona os quadros quando a execução termina. Add from Capture History… importa quadros de uma sessão que já existe, por exemplo uma execução feita por um colega no Mac de staging.

No exemplo, o fluxo de convite é recapturado diretamente. O caminho de faturamento já havia sido capturado no staging no dia anterior, então seus 2 quadros vêm de Add from Capture History…. O seletor permite expandir essa sessão e marcar apenas os 2 quadros necessários.

Receita para recapturar o fluxo de convite

O fluxo de convite tem 5 cliques: Invite, o campo de e-mail, o menu Role, a opção Admin e Send invite. Cinco etapas cabem no limite do plano gratuito, de 5 etapas por execução do Action Capture. Um caminho mais longo exige o Temposhot Pro ou a divisão em duas execuções.

Use o mesmo tipo de destino e o mesmo estilo de marcador da execução original. Um guia em que as páginas 6 a 9 usam marcador de círculo e as demais usam retângulo parece remendado, mesmo que cada etapa esteja correta.

Mantenha o mesmo tamanho da janela

Um destino Specific Window captura a janela em seu tamanho atual. Se a janela do navegador tinha 1440 pixels de largura nas páginas originais, redimensione-a para a mesma largura antes da recaptura. Uma largura diferente altera o layout da página e o tamanho do texto em comparação com as 33 páginas inalteradas.

Screenshot Resolution Checker mostra o tamanho em pixels de uma imagem de página exportada. Verifique uma página antiga e uma nova. As larguras devem coincidir.

Revise texto, anotações e privacidade

Novas capturas costumam quebrar elementos ao redor:

• Títulos que citam um rótulo antigo: "Selecione Add member" quando o botão agora diz Invite.
• Setas e marcadores que agora apontam para um espaço vazio.
• Enquadramento que corta um controle que foi movido.
• Telas novas que mostram dados que as antigas não mostravam, como uma barra lateral nova com nomes.

Reaplique Focus on action nas páginas do Action Capture, ou Custom nas demais. Oculte dados pessoais novos com Blur (B, Pro).

Pesquise o rótulo antigo em todas as páginas

Um controle renomeado costuma aparecer em mais lugares do que nas páginas que o mostram. No exemplo, "Add member" aparece nos títulos das páginas 6 e 14, mas também na descrição da página 3, que explica onde encontrar a página Members. Leia o Page title e a Description de cada página no Page Inspector e liste todos os lugares em que o rótulo antigo aparece. Corrija todos na mesma edição.

Mantenha o enquadramento das páginas vizinhas

As páginas do Action Capture aceitam cinco níveis de enquadramento: Wide, Relaxed, Balanced, Close e Tight. Se as páginas 5 e 10 usam Balanced, defina as páginas 6 a 9 também como Balanced. Níveis misturados fazem o zoom mudar de uma página para outra, o que parece um erro.

Pressione F para abrir o editor de enquadramento de uma página. Reset to action recria o enquadramento automático em torno do ponto clicado se um recorte manual saiu errado.

Teste o guia completo

Siga o guia inteiro na versão atual, da primeira página até o resultado, usando uma conta de teste. Uma página substituída ainda pode quebrar o fluxo, por exemplo quando a mudança também move a etapa seguinte.

Atualize Verified version e a data de Last verified somente depois que o teste for aprovado.

O que o teste encontrou no exemplo

No exemplo da 4.3, o teste de ponta a ponta detectou um problema que a revisão das páginas não viu. A página 10 ainda pedia ao leitor que feche a caixa de diálogo depois de enviar o convite, mas a 4.3 fecha a caixa automaticamente. A captura da página 10 continuava correta, então nem o inventário nem o Compare Images a sinalizaram. Só seguir as etapas revelou o problema.

Corrija a descrição e repita o teste a partir da página 5. Um teste parcial, começando na página anterior à primeira alteração, basta quando o restante do guia não mudou.

Escolha quem executa o teste

Quem recapturou as páginas é o pior testador, porque já sabe onde está cada controle. Um responsável de seção ou um colega do suporte que não participou lê o guia como um cliente leria. No exemplo, o responsável pela squad de segurança testou a seção de membros e encontrou o problema da página 10 em cerca de 10 minutos.

Entregue ao testador o PDF exportado, e não o Document no editor. Assim, o teste cobre o arquivo que os leitores recebem, incluindo a ordem das páginas, a página de capa e a qualidade das imagens.

Teste novamente após hotfixes

Um hotfix entre duas versões pode alterar um rótulo sem nota de versão. Se o suporte relatar uma divergência dentro do ciclo de 6 semanas, repita o mesmo mapeamento: encontre as páginas no inventário, substitua-as e execute um teste parcial a partir da página anterior à alteração. Adicione a versão do hotfix ao campo Verified version, por exemplo 4.3.1.

Arquive somente quando os leitores precisarem do histórico

A maioria dos leitores quer apenas o guia atual. Mantenha versões antigas quando alguém ainda usa a versão antiga do produto, como clientes de uma versão de longo prazo, ou quando uma regulamentação exige um registro.

Ao arquivar, identifique claramente o arquivo antigo no nome e na capa, por exemplo invite-teammate_v4.1_archived.pdf. Documents e Capture History ficam armazenados localmente no Mac. Por isso, arquive os arquivos exportados no armazenamento compartilhado, em vez de depender do Mac. Excluir o trabalho do Action Capture pode remover o Document correspondente, então mantenha o Document de origem até que o guia seja aposentado.

Layout de pastas para exportações

Um layout fixo de pastas mantém o arquivo atual fácil de encontrar. Defina o Export path em Settings > General como a pasta de trabalho do guia e, em seguida, mova os arquivos finalizados para o lugar.

Somente a pasta current é vinculada na central de ajuda ou na intranet. Os arquivos arquivados continuam acessíveis para clientes em versões antigas, mas ninguém chega a eles por acidente.

Acompanhe a retenção do Capture History

O Capture History mantém 30 sessões por padrão, com limite de 1 a 500 em Settings > History. Uma equipe que recaptura a cada 6 semanas em vários guias pode chegar a 30 sessões em poucos ciclos. O Document mantém as próprias cópias de cada imagem, então excluir sessões antigas não prejudica o guia. Porém, os quadros brutos para reutilização posterior deixam de existir.

Registre a manutenção com este modelo

Mantenha uma linha por guia em uma planilha ou na sua ferramenta de documentação:

• Nome do guia e local do arquivo.
• Responsável.
• Telas exibidas.
• Versão verificada e data da última verificação.
• Problemas abertos relatados pelo suporte ou pelos leitores.
• Próxima verificação por amostragem agendada.

Uma revisão semanal curta dessa lista detecta mudanças enquanto ainda são pequenas. Uma limpeza anual as encontra depois que os leitores já as viram.

Exemplo de registro após a versão 4.3

Campo	Valor
Guia	Guia do administrador, current/admin-guide_v4.3.pdf
Responsável	Líder de documentação, com quatro responsáveis de seção
Telas exibidas	Members, Invite dialog, Roles, Billing, Invoices, Audit log
Versão verificada	4.3, última verificação no dia do lançamento
Problemas abertos	Nenhum
Próxima verificação por amostragem	Versão 4.4, 6 semanas depois

Hábitos que fazem as capturas durarem mais

Algumas capturas quebram a cada lançamento e outras continuam válidas por anos. A diferença está principalmente no quanto elas são enquadradas e nos dados que mostram.

Perguntas frequentes

Com que frequência a documentação com capturas de tela deve ser revisada?

Após cada versão que altera uma tela exibida no guia, além de uma verificação por amostragem em intervalo fixo, como uma vez por trimestre, para guias sem outro gatilho.

Como reduzir a frequência com que as capturas quebram?

Recorte bem em torno do painel relevante com Framing, evite datas e nomes nas capturas e nomeie os controles no texto. Assim, o leitor continua acompanhando quando surge uma pequena mudança de estilo.

Preciso recapturar o guia inteiro após um redesenho?

Em caso de mudança completa de layout ou de tema, sim. Para um botão renomeado ou um controle movido, substitua apenas as páginas afetadas.

Exportar o Document novamente sobrescreve o PDF antigo?

Não. Se já existir um arquivo com o mesmo nome no Export path, o Temposhot acrescenta um número ao nome do novo arquivo. Mova ou renomeie o arquivo antigo primeiro, ou substitua a cópia publicada manualmente.

Posso atualizar páginas de um guia criado com capturas manuais?

Sim. Use Upload images… para adicionar novos arquivos de imagem ou Capture new images… para capturá-los. O Document trata todas as páginas da mesma forma, independentemente da origem. Somente as páginas do Action Capture têm um ponto de clique para Focus on action.

Quanto tempo uma atualização parcial leva em comparação com uma recaptura completa?

No exemplo de 40 páginas, substituir e revisar 7 páginas levou cerca de 35 minutos. Uma recaptura completa também exigiria redigitar ou conferir 40 títulos e descrições e reaplicar as anotações em todas as páginas. Por isso, levaria várias vezes mais tempo.

Transforme seus cliques em um guia passo a passo claro

Action Capture recaptura apenas as etapas alteradas e as adiciona ao Document existente. Baixe o Temposhot e atualize o guia começando pela versão verificada mais antiga.