Clube do Livro VTEX: Edição técnica

Esse 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, em que discutimos o livro The Product is Docs. Neste post nós vamos discutir o pilar da escrita no contexto de Technical Writing. Iremos abordar quais decisões precisamos tomar durante o processo de escrita, como editar uma documentação e como colaborar com outros indivíduos para produzir documentação técnica. Veja abaixo os artigos que fazem parte da seção Escrita.

Autoria colaborativa (Collaborative Authoring)
Decisões de documentação (Documentation Decisions)
Edição técnica (Technical Editing)

O capítulo sobre edição técnica aborda o processo de revisão de textos produzidos por technical writers e como ele se encaixa no processo de documentação como um todo.

Na indústria de software, a tendência é que lançamentos ocorram com uma frequência exponencial e a documentação precisa acompanhar as evoluções do produto. Por conta dessa velocidade, pode ser um desafio encontrar tempo para a edição técnica. Mesmo assim, é importante que esse processo seja adotado para garantir a qualidade da documentação do produto.

Edição técnica é o processo de oferecer feedback para technical writers sobre a efetividade do seu conteúdo. A edição técnica ajuda a assegurar que a documentação técnica é acessível, clara, útil e relevante para o público pretendido. (p. 156)

O que é edição técnica?

A edição técnica é muito mais do que apenas uma revisão textual. Editores técnicos analisam:

Questões de estilo
Usabilidade
Clareza e coesão
Terminologia consistente
Definição de público
Objetividade do texto

Esse trabalho não precisa ser realizado por alguém com o cargo de editor, pode ser feito por um technical writer, um gerente de produto, um responsável da área de marketing ou de customer success, por exemplo.

O que a edição técnica acrescenta à documentação?

A edição técnica é um mecanismo eficiente para obter feedback sobre a sua documentação e saber se ela alcança o objetivo esperado. Abaixo, resumimos as principais razões para inseri-la no fluxo de trabalho da sua equipe de documentação:

Ganhar uma perspectiva diferente sobre o seu conteúdo.
Assegurar a qualidade da documentação técnica.
Manter um estilo consistente ao longo do texto e entre todo o time.
Assegurar a adequação ao guia de estilo.
Otimizar o design da informação.

Não tem um time de edição? Seja o seu próprio editor

Técnicas para revisar o seu próprio texto podem otimizar a escrita de forma independente em qualquer etapa do desenvolvimento da informação. Veja as principais técnicas indicadas pelo time do Splunk para auto edição:

Criar o seu próprio guia de estilo ou se apoiar em um guia que seja utilizado por technical writers de outras empresas, como o Splunk Style Guide, o Google Developer Documentation Style Guide, ou o Microsoft Writing Style Guide.
Desenvolver uma lista de itens que você precisa conferir antes de publicar cada documentação.
Utilizar ferramentas que auxiliam a detectar erros gramaticais ou de digitação e ferramentas para validar o código.
Ler o texto em voz alta após escrever, para perceber como o seu texto soa para quem está lendo e identificar frases confusas que precisam ser reformuladas.
Deixar o texto “de molho”, ou seja, ir descansar, caminhar ou focar em outras tarefas para depois retornar ao texto e analisá-lo com um novo olhar posteriormente.
Observar alguém lendo o seu conteúdo para entender exatamente quais são os pontos de dúvida ou dificuldade.
Experimentar novas formas de organizar e apresentar o conteúdo.
Conferir o feedback dos usuários e utilizar os insights deles para avaliar o quanto o conteúdo cumpre com o seu objetivo e em quais aspectos ele pode ser aprimorado.
Escrever como se tudo fosse para o seu portfólio. O trabalho selecionado para o seu portfólio deve demonstrar as suas melhores habilidades como technical writer, então vale escrever e avaliar todo o seu conteúdo como se ele tivesse esse objetivo.
Manter-se atualizado com as principais tendências em Technical Writing e desenvolvimento de informação. Participe de comunidades de Technical Writing, cursos e conferências. Leia livros e trabalhos acadêmicos relacionados à área.

Timing é tudo

No caso do Splunk, o timing da edição é flexível, ou seja, a edição técnica pode fazer parte de qualquer etapa do processo editorial. Os tech writers do time têm liberdade para enviarem seus textos para edição quando puderem e precisarem. Geralmente, para edição de rascunhos, o melhor momento para a edição é entre a revisão técnica do conteúdo e a publicação do artigo.

O segredo para encontrar o melhor timing para a edição está em enviar pequenas quantidades de rascunhos de cada vez. Isso proporciona um processo editorial mais rápido e eficiente e facilita o trabalho em harmonia com o time de desenvolvedores do produto.

Vale lembrar que, se o prazo estiver curto, é importante indicar ao editor pontos específicos em que você gostaria que ele focasse durante a revisão do seu trabalho. Isso ajuda a otimizar o tempo de edição.

Outro ponto que ajuda na organização do time é levar em consideração o nível de experiência de cada tech writer. Se a equipe tiver novos membros, pode ser útil se planejar para que eles sejam acompanhados por um editor em um momento inicial, por exemplo.

Não existe momento errado para a edição técnica. Ela pode agregar valor em qualquer momento do processo de produção da documentação.

Editores e tech writers: trabalho em equipe

O olhar para a edição técnica do Splunk é colaborativo: o objetivo dos editores é aconselhar e contribuir com o time para construir a melhor documentação possível para o público, e não julgar ou indicar um jeito “certo” de se escrever.

Listamos abaixo algumas boas práticas do time do Splunk para otimizar esse processo no dia a dia:

Apresentar o fluxo de trabalho de edição para novos tech writers durante o onboarding.
Manter um repositório compartilhado de links e conteúdos úteis sobre Tech Writing.
Organizar uma reunião regular em que o time de documentação discute questões de estilo e desafios que encontraram durante a escrita.
Oferecer workshops de escrita e promover treinamentos práticos.
Conduzir uma pesquisa interna anual para verificar as percepções dos tech writers e dos editores sobre o dia a dia de trabalho e criar um plano de ação com base nos insights gerados pela pesquisa.
Não tornar a edição uma etapa obrigatória que bloqueia o processo de documentação. Confiar no time para saber quando é necessário passar pelo processo de edição.
Oferecer feedback como sugestão, em vez de correção.
Criar um formulário de solicitação de edição para que tech writers indiquem qual é o público alvo da documentação, quais são os objetivos de aprendizado e se o conteúdo já passou por revisão técnica, por exemplo.
Convidar tech writers a atuarem como editores por uma semana para aprenderem sobre o processo de edição e conhecerem essa possibilidade de carreira.

Editando documentação como código (docs like code)

A indústria de software tem adotado progressivamente a cultura de docs like code. Isso significa que tech writers passam a escrever documentação utilizando as mesmas ferramentas que desenvolvedores utilizam para desenvolver código, como o GitHub, por exemplo. Nesses casos, as entregas de documentação e de produto são alinhadas em uma dinâmica de CI/CD — integração contínua e entrega contínua.

É importante adaptar os processos existentes de Tech Writing e edição para acompanhar essa tendência. Editores, por exemplo, precisam se familiarizar com pull requests e merge requests para atuarem nessa lógica de fazer a edição técnica no mesmo ambiente que tech writers e desenvolvedores utilizam.

Vale lembrar que é a colaboração entre o time que torna o processo de edição bem-sucedido, não as ferramentas e processos. Adotando a visão docs like code ou não, o importante é ter processos bem alinhados na equipe.

Criar uma cultura de melhorias contínuas

A edição técnica ajuda technical writers a escreverem melhor e assegura a qualidade da documentação do time como um todo. O feedback dos editores sobre o texto ajuda a tomar decisões sobre a escrita, como quais trechos do conteúdo manter ou remover e qual escolha de palavras funciona melhor para o público, por exemplo.

Esse processo é uma oportunidade de pensar mais a fundo sobre a parte de writing do dia a dia de Technical Writing, analisar o propósito e a eficácia de cada texto. Afinal, o objetivo principal da documentação é contribuir para que os clientes sejam bem-sucedidos no uso do produto.

Citações

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

Citação	Página
A edição técnica trata de questões de estilo, usabilidade, claridade, coesão, terminologia consistente, definição de audiência e minimalismo.	157
A edição técnica traz perspectiva, qualidade, estilo consistente e princípios de um bom design de informação para a documentação.	157
Ouvir como os outros leem o que você escreve pode lançar uma nova luz sobre problemas no seu conteúdo que você não identificaria por conta própria.	157
A edição técnica assegura a qualidade da linguagem e do design da documentação de software.	158
Os editores estão em uma posição única para ter uma visão geral do conteúdo, tornando a edição técnica a peça-chave para alcançar uma consistência de estilo em todo um corpus de documentação, especialmente quando múltiplos autores contribuem para esse conjunto de artigos.	158
Ter vários autores escrevendo bem e com um estilo consistente é o mais difícil de tudo.	158
Um guia de estilo contém respostas para perguntas comuns sobre o conteúdo para que autores possam continuar escrevendo em vez de ficar presos a uma dúvida sobre estilo ou iniciar uma discussão sobre qual esquema de capitalização usar em cabeçalhos, como estruturar links, ou se "they" é é um pronome singular aceitável, por exemplo.	159
Guias de estilo podem poupar o seu tempo para que você não precise lembrar de decisões tomadas anteriormente — ou tomar decisões novamente sobre o mesmo assunto cada vez que você se deparar com algum dilema durante a escrita.	159
Você pode ser a pessoa que estabelece o tom e a voz da sua empresa.	160
Como technical writer, você pode se encontrar no papel de arquiteto de informação ou estrategista de conteúdo. Um editor técnico pode ajudar você e toda a equipe a desenvolver modelos de informação ou organizar conjuntos de documentação para a usabilidade.	160
Faça uma lista de coisas que você deseja conferir antes de publicar uma documentação e verifique se cada artigo cumpre esses requisitos.	162
Experimente diferentes maneiras de apresentar ou organizar seu conteúdo. Não confie no que você fez antes só porque funcionou em um contexto diferente.	164
Se o seu prazo estiver acabando para uma edição, solicite ao seu editor ou revisor um nível específico de edição. Informe seu revisor sobre no que você quer que ele se concentre e informe se há um aspecto do artigo que você acha que precisa de uma atenção maior na revisão.	166
O nível de experiência do tech writer também pode ser levado em conta no momento das edições. Se você tiver novos membros da equipe, pode ser útil planejar para que eles trabalhem com um editor e passem mais tempo revisando seus primeiros projetos. Esta prática ajuda os novos autores a aprenderem a escrever com o tom de voz da sua empresa, a seguir o guia de estilo e a manter a consistência em toda a documentação.	167
Editores agregam valor em qualquer momento do processo em que um autor desejar apoio. Nunca há um momento errado para editar seu conteúdo.	167-168
Organizamos uma reunião regular na qual toda a equipe de documentação discute questões de estilo e desafios de escrita. Encorajamos os tech writers a enviarem solicitações de temas a serem abordados, para que o programa seja direcionado para assuntos que lhes são úteis.	168