Clube do Livro VTEX: Mantendo o conteúdo existente

Este post faz parte de uma série de conteúdos produzidos pelo time de tech writers da VTEX em nosso projeto do clube do livro. Neste post nós vamos discutir o pilar de Processos e ferramentas no contexto de Technical Writing. Iremos abordar como fazer a manutenção da documentação existente e pesquisar para escrever documentação técnica. Veja abaixo os artigos que fazem parte da seção Processos e ferramentas.

• Mantendo o conteúdo existente
• Pesquisa para technical writers

Toda página de documentação é uma oportunidade para causar uma boa impressão no cliente, não importa o quão antiga ela seja. Por isso, é importante saber equilibrar a documentação de novas funcionalidades do produto com a manutenção de artigos existentes.

Não importa há quanto tempo a sua documentação existe, toda página ou artigo de um conjunto de documentação representa uma oportunidade de ter uma primeira impressão positiva nos seus usuários. (p. 105)

Por que o conteúdo precisa de manutenção?

A manutenção da documentação é uma tarefa tanto reativa quanto proativa, ou seja, essa necessidade pode surgir a partir de uma demanda externa ou do próprio time de tech writers.

Ajustar a documentação pode ser importante por conta da atualização de uma funcionalidade ou simplesmente por uma necessidade de melhoria na documentação. Essa demanda pode chegar de feedbacks de usuários, redefinição do escopo do público, adequação a objetivos de aprendizado, adequação a um guia de estilo, mudanças de terminologia, mudanças na plataforma de documentação utilizada, correção de erros ou melhorias no texto, entre outros tipos de situação.

Qualquer situação deste tipo pode ser uma oportunidade para revisar o material como um todo e considerar ajustes mais amplos.

Como fazer atualizações

Sempre que surgir a necessidade de uma atualização na documentação, é importante pensar sobre o escopo ou o impacto dessa mudança: será um ajuste simples em uma informação pontual ou será preciso reescrever o artigo por completo para revelar novas perspectivas sobre uma funcionalidade?

Ao lidar com atualizações com um escopo médio, pode ser difícil escolher qual desses caminhos seguir.

Para ilustrar, o livro cita o exemplo da atualização de uma funcionalidade na interface de um produto digital. Essa nova versão disponibilizaria novas opções de configuração que não estavam disponíveis anteriormente na interface, apenas de forma manual, editando um arquivo de código.

Se na documentação atual existe uma tabela com nomes e descrições para essas configurações manuais, qual seria a melhor opção para incluir a nova informação: fazer um pequeno ajuste na tabela ou reescrever esse trecho completamente?

Em um cenário como esse, avalie o impacto que a mudança apresenta para os usuários. Mesmo que seja mais simples e rápido fazer um ajuste pontual, uma documentação mais completa deve levar em consideração questões como:

• Se a atualização do produto permite que a nova configuração seja feita por usuários com perfil menos técnico. Neste caso, pode ser necessário adequar o resto da linguagem do artigo para esse público.
• Se as atualizações podem gerar novos fluxos de utilização do produto.
• Se existem novos casos de uso e exemplos práticos para refletir os novos cenários.

Considerando o nível de impacto do exemplo anterior, pode fazer mais sentido reorganizar o artigo como um todo e expandir o conteúdo com as novas alterações.

De um modo geral, é sempre uma boa ideia ter em mente os impactos de uma mudança além do seu conteúdo, ou seja, também considerar as dependências entre a funcionalidade atualizada e as outras áreas do produto.

Planejando atualizações

Uma dica importante para lidar com atualizações é se planejar para fazer esses ajustes. Não é recomendável deixar de lado a documentação existente para focar somente na documentação de novas funcionalidades. Durante o seu planejamento, leve em consideração os pontos a seguir.

Ferramentas de publicação

Dependendo da ferramenta utilizada pela sua equipe para publicar a documentação, é possível que esse processo exija a conversão de documentos e o alinhamento entre diferentes áreas, como a área de produto e a área de Tradução, por exemplo.

Atente-se para os tipos de ajustes e prazos (timing)

Cada tipo de ajuste na documentação exige um prazo (timing) específico.

No caso de uma nova funcionalidade ou de mudanças em uma funcionalidade existente, a documentação precisa ser atualizada ao mesmo tempo do lançamento.

Ajustes provenientes de feedback de clientes ou correções de erros devem ser realizados assim que possível.

Mudanças de terminologia no produto ou mudanças no guia de estilo devem ser alinhadas com o time de editores e gerentes de produto.

Aprofundamento, melhorias gerais e edição de textos para gerar mais clareza podem ser mudanças a longo prazo, que requerem mais tempo e planejamento.

Dê um passo para trás antes de mergulhar em algo

Se você precisa fazer ajustes significativos em um conteúdo, faça um planejamento antes de começar a aplicar as mudanças necessárias.

Sincronize grandes ajustes com o timing dos lançamentos

Converse com a sua equipe sobre planejar atualizações amplas de documentação para coincidir com o momento de lançamento de novas funcionalidades. Tenha em mente como grandes mudanças na documentação podem afetar os usuários.

Encontre tempo para grandes ajustes

É fundamental buscar oportunidades para realizar grandes ajustes na documentação, por mais que seja complexo conciliar essa tarefa com o dia a dia de lançamentos e outras tarefas de tech writers.

O time do Splunk, por exemplo, sugere usar hack weeks ou hackathons para experimentar novos formatos de documentação ou fazer mudanças que inovem o conteúdo atual.

Outra possibilidade é dividir um grande plano de atualização em partes menores: em vez de fazer todas as alterações de uma vez, pode ser mais eficaz dividir um planejamento em pequenas tarefas e reservar horários no seu calendário para focar nessas tarefas, alinhando cada entrega com o seu gestor e o time de produto. Até os tech writers mais ocupados conseguem encontrar uma hora ou duas por semana para se dedicar a ajustes no conteúdo atual sem sacrificar outras responsabilidades.

De forma geral, a manutenção do conteúdo existente precisa ser constante, pois é essencial para garantir a confiança dos seus clientes. Porém, é importante saber priorizar essa atividade de acordo com as métricas de documentação, como o número de acessos e o número de tickets abertos para o suporte sobre o assunto.

Citações

Traduzimos livremente alguns trechos do livro que mais chamaram nossa atenção:

Citação	Página
Manutenção é uma atividade reativa e proativa. Tech writers podem embarcar em projetos de manutenção de documentação a partir de atualizações de funcionalidades ou de forma apartada do desenvolvimento do produto.	105
Quando você faz atualizações (na documentação) por qualquer motivo mencionado aqui, trate isso como uma oportunidade para olhar para o material como um todo e considerar atualizações mais amplas ou mais profundas.	109
Quando uma atualização ou necessidade de manutenção surgir, pause e reflita sobre o escopo ou o impacto da mudança que você pretende realizar.	110
Independentemente do escopo da mudança em uma funcionalidade, tech writers sempre precisam considerar as dependências entre a funcionalidade atualizada e outras áreas do produto.	113
Não negligencie o estado da documentação existente mesmo se você precisar focar na documentação de novas funcionalidades ao mesmo tempo.	114
Na maioria dos casos, até os tech writers mais ocupados podem encontrar uma hora ou duas a cada semana para se dedicar ao trabalho de manutenção da documentação sem sacrificar outras responsabilidades.	117
A manutenção do conteúdo precisa ser um item frequente e importante na lista de tarefas de todo tech writer. É uma ferramenta essencial para construir e sustentar a confiança dos clientes. Também é um ótimo meio para tech writers aprofundarem seu conhecimento sobre o produto e refinarem continuamente a estrutura ou arquitetura informacional e organizacional que sustenta qualquer conteúdo.	117