VTEX team 
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) - Em breve
A colaboração é inerente ao trabalho do tech writer, seja com outros tech writers em projetos compartilhados ou adjacentes, ou com Subject Matter Experts, que são especialistas em determinados assuntos.
O capítulo Collaborative Authoring do livro The Product is Docs propõe uma reflexão sobre esse tema e oferece dicas para colaborar de forma eficiente com outros profissionais no dia a dia.
Na visão do time de documentação do Splunk, o mercado de Technical Writing tem passado por uma mudança de mentalidade, partindo de um modelo mais estático de desenvolvimento de informação para modelos mais colaborativos. A tendência é que os autores deixem de se comportar como “donos” da documentação e que esta passe a ser construída pelo time como um todo através de ferramentas como wikis.
A combinação entre ferramentas, educação e tendências da indústria nos conduzem fortemente a um verdadeiro modelo de autoria colaborativa. (p. 36)
Trabalhar com múltiplos autores
O livro recomenda as seguintes estratégias para trabalhar com múltiplos autores no processo de documentação:
- Usar o guia de estilo da empresa, para alcançar uma escrita consistente entre todo o time de technical writers. Se a empresa não tiver diretrizes consolidadas, é importante criar um documento que formalize isso.
- Ter um editor na equipe, para realizar a checagem do conteúdo de forma padronizada, antes de sua publicação.
- Revisar o trabalho de outros technical writers da equipe que escrevem sobre assuntos correlatos, garantindo que as informações não se contradigam, não se repitam e nem se sobreponham.
- Estabelecer um processo formal de peer-review (i.e., revisão de colegas de equipe) para que os tech writers tenham visibilidade do trabalho da equipe como um todo.
- Ler o trabalho de outros tech writers casualmente, sem precisar se comprometer com um processo formal de edição ou revisão.
- Ser flexível e adaptável para entender que a documentação é um produto coletivo do time.
Trabalhar com autores técnicos
As sugestões do time do Splunk para trabalhar com Subject Matter Experts que apoiam o processo de documentação são:
- Saber explicar o motivo das suas alterações no texto a partir da perspectiva de Tech Writing.
- Estar preparado(a) para receber feedbacks dos especialistas e aplicar as devidas melhorias na documentação com base nas sugestões recebidas. Se decidir não agir a partir de determinado feedback, é importante saber justificar os motivos para isso.
- Ser flexível sobre as regras do guia de estilo da empresa quando necessário. Algumas vezes, pode ser mais importante priorizar a colaboração com o especialista e focar em melhorias no texto posteriormente.
O quão ampla a colaboração deve ser?
O Splunk tem um sistema baseado no modelo de wiki, em que qualquer funcionário pode contribuir e editar a documentação.
Os aspectos positivos desse modelo são encorajar o público interno a se engajar com a documentação, reportar problemas e compartilhar a responsabilidade sobre a documentação.
Por outro lado, esse formato facilita a inclusão de informações incorretas ou redundantes, e textos confusos ou fora de contexto. Além disso, o modelo de wiki pode gerar um trabalho extra para o time de documentação, que precisa inserir na rotina a atividade de monitorar as contribuições realizadas pelos demais funcionários da empresa.
A realidade no Splunk é que, apesar de existir a liberdade para qualquer funcionário editar conteúdo, poucos realmente o fazem e quem se compromete com isso edita de forma responsável e consciente. Por isso, no caso do Splunk, as vantagens de adotar o modelo de wiki são maiores que as desvantagens.
Em geral, para decidir entre um modelo mais colaborativo ou mais restrito, é imprescindível avaliar o contexto específico do seu time de technical writers e o tipo de documentação da sua empresa.
Citações
Traduzimos livremente alguns trechos do livro que mais chamaram nossa atenção:
| Citação | Página |
| Em alguns casos, redatores trabalham de forma próxima em entregáveis compartilhados. Em outros, os redatores coordenam os seus trabalhos para garantir a consistência e a relevância da documentação. Em outras situações, redatores colaboram com especialistas técnicos para cumprir solicitações de clientes e outros requisitos de documentação. | 36 |
| (...) vale a pena ajustar as suas práticas para produzir o melhor resultado para o cliente com o processo mais eficiente. | 37 |
| (...) quando qualquer funcionário pode editar a documentação, eles podem introduzir informação incorreta ou redundante. | 39 |
| A baixa barreira para a participação encoraja usuários internos a se engajarem com o processo de documentação, reportarem problemas e compartilharem um senso de propriedade sobre o produto publicado. Ela também proporciona um mecanismo de feedback que você pode utilizar para revisões técnicas, quando o revisor pode trabalhar diretamente no mesmo sistema que você. | 39 |
| No Splunk, o time de documentação utiliza leitores RSS para monitorar alterações em conteúdo direcionado para clientes e revisar essas mudanças. Apesar de qualquer funcionário poder editar a documentação do Splunk, a realidade é que muitos poucos deles realmente o fazem. | 39 |
Clube do Livro VTEX: The Product is Docs