Clube do Livro VTEX: Pesquisa para technical writers

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

Para escrever uma documentação que informa e explica um assunto de forma eficiente para o seu público, é importante garantir três elementos principais:

• Contexto técnico.
• Uma técnica para descobrir e comunicar os pontos mais relevantes sobre o produto.
• A melhor forma de expressar essas informações.

Com esses pontos em mente, o time do Splunk sugere que tech writers utilizem uma abordagem jornalística como ponto de partida para a documentação técnica.

Faça uma pesquisa prévia

Antes de adentrar uma nova área técnica, é importante reservar um tempo inicial para ganhar mais contexto e aprender os conceitos essenciais relacionados àquele assunto. Não é necessário que você se torne um especialista, mas você deve ser capaz de se comunicar com as pessoas da área.

Além da contextualização técnica, busque também ganhar contexto do ponto de vista do negócio:

• Por que a sua empresa está executando este projeto?
• Qual o estudo de caso do projeto?
• Quem está envolvido nele? Existe documentação de design?
• Como o projeto está sendo monitorado?

Se existirem apresentações, websites e especificações do projeto, considere ler e ajudar a produzir tais materiais. Se o projeto for monitorado em um sistema como o Jira, acompanhe as mudanças no projeto e nas tarefas relacionadas. Saiba quem está trabalhando no projeto e se apresente ao time.

Verifique os fatos

Procure escrever a partir de fontes primárias. Teste você mesmo o produto o máximo possível para entender o que o seu público precisa saber.

Evite fazer perguntas vagas para desenvolvedores sem antes testar as funcionalidades, pois você pode perder a credibilidade com as suas fontes e parecer preguiçoso(a) ou sem perspicácia técnica. Se for necessário solicitar permissões e outras autorizações, faça isso.

Se você não puder testar o produto, elabore perguntas com cuidado e faça uma verificação cruzada com múltiplas fontes.

Quem são as pessoas certas para responder suas perguntas?

É importante conversar com os desenvolvedores responsáveis pela funcionalidade, mas também com o gerente de produto para entender os objetivos do usuário que o produto procura atender. Considere conversar também com uma pessoa que trabalha com atendimento ao cliente ou um engenheiro de QA.

Essas pessoas serão suas fontes de informação: se você fosse um repórter jornalístico, seriam seus entrevistados.

Fontes são ocupadas, e suas perguntas provavelmente não são a prioridade delas. Depois de um intervalo de tempo razoável, pergunte novamente. Seja tão alegremente persistente quanto um golden retriever. Dê-lhes um prazo. (p. 145)

Quais são as perguntas certas?

Durante o processo de investigação, faça as perguntas certas caso você deseje focar em ajudar o seu leitor a resolver problemas do mundo real e não em documentações conceituais. As perguntas certas, no entanto, irão depender do seu público.

Faça as perguntas que respondem o que os seus leitores querem saber. (p. 145)

Como formular uma pergunta?

Escolha a melhor forma de diálogo de acordo com o tipo de pergunta que você precisa fazer e de acordo com as preferências das suas fontes. Se for fazer muitas perguntas, considere marcar uma conversa rápida em vez de fazer várias perguntas de uma vez via chat, por exemplo.

Para obter uma resposta não ambígua, mantenha a sua pergunta o mais simples possível. Se puder ser uma pergunta de “sim” ou “não”, melhor ainda. Para obter uma resposta discursiva, faça o oposto: formule uma pergunta aberta.

Comunique o significado das informações

De forma resumida, é importante ser claro(a) na sua explicação e na terminologia utilizada ao escrever a documentação técnica. Evite ambiguidades e informações vagas ou pouco objetivas. Procure seguir os princípios editoriais definidos pelo seu time de documentação para garantir a qualidade do texto.

Citações

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

Citação	Página
Quais são as perguntas certas a serem feitas? Depende de quem é o seu público-alvo.	140
Ao embarcar em um novo campo técnico, dedique algum tempo no início para sondar o território, obter contexto e aprender o essencial.	141
Descubra por que sua empresa está seguindo este projeto. Qual é o case de negócio em jogo? Se houver especificações, websites de projetos e apresentações, leia-os e considere ajudar a escrevê-los — eles são documentos essenciais e sua habilidade de escrever pode ajudar a garantir que eles sejam claros e completos. Se o projeto for acompanhado a partir de um sistema de gestão de tarefas como o Jira, monitore o projeto em busca de mudanças e observe os problemas. Saiba quem está na equipe do projeto e se apresente.	143
Escreva a partir de fontes primárias. Determine o que seu leitor precisa saber e verifique as informações o máximo possível.	143
Evite a situação constrangedora de perguntar a um desenvolvedor como funciona um recurso, apenas para ser questionado: "Você tentou?” Você não tentou.	143
Ao escrever sobre procedimentos, teste um passo e escreva sobre ele imediatamente.	143
Como um repórter, você precisa ser um entrevistador competente. Faça as perguntas certas, para as pessoas certas, do jeito certo.	144
De que tipo de resposta você precisa? Para obter uma resposta inequívoca, faça uma pergunta simples. Quanto mais simples, melhor. Pode ser uma pergunta de sim ou não? Para obter uma resposta discursiva, faça o contrário: faça uma pergunta em aberto. Para obter uma resposta rápida, faça uma pergunta de cada vez, ao invés de agrupá-las, a menos que sua fonte prefira que você o faça.	146
Cuidado com a palavra "deve" — ela é indicativa de um significado oculto, expressando ou uma recomendação ou uma exigência.	147
Para transmitir uma exigência, use uma versão da palavra "precisa" e depois explique o motivo dessa obrigatoriedade.	147
Se alguém precisa saber como funciona um recurso para afinar seu desempenho, explique-o nesses termos para que a pessoa possa configurá-lo com sucesso.	148
Sempre agradeça sinceramente às pessoas que oferecem ajuda. Todas as vezes.	149