Empatia, priorização, integração e divulgação: os 4 propulsores da jornada de documentação da VTEX

Embora muitas empresas de tecnologia já reconheçam hoje a importância de uma boa documentação para o êxito dos seus produtos digitais, ainda encontramos no mercado muita inércia nesta frente.

Na prática, todas empresas desejam os resultados concretos proporcionados por uma documentação técnica de qualidade, sem dúvidas. Mas será que estão prontas para investir esforços e reconhecer que esta jornada requer, acima de tudo, comprometimento?

Com um time reduzido de tech writers e um longo histórico de produtos desenvolvidos sem documentação adequada, o nosso time da VTEX sentiu as dores de um crescimento acelerado sem o devido suporte para a escalabilidade do conhecimento. Assim, aprendemos por experiência própria que o desafio de produzir uma documentação técnica de primeira linha é tão grande quanto a sua importância para o futuro da empresa.

A nossa jornada até aqui foi árdua, mas muito recompensadora! É com base nela que hoje compartilhamos alguns insights que foram fundamentais para a estruturação da nossa documentação, agrupados em quatro grandes pilares: empatia, priorização, integração e divulgação.

Empatia para escrever documentações funcionais

• 

A arte de se comunicar se baseia na capacidade de transmitir mensagens de um emissor para um receptor, sem eventuais ruídos que atrapalhem a troca de informações. Se você, como emissor, não entende sobre a mensagem que quer transmitir e sobre o receptor que irá recebê-la, como espera obter sucesso na sua comunicação?

Sem o devido entendimento do produto e de seus usuários, uma empresa de tecnologia dificilmente conseguirá superar o obstáculo da documentação na sua trajetória de crescimento.

Por soar clichê, a empatia é um ponto fundamental muitas vezes preterido na jornada de documentação. Com a VTEX não foi diferente! Não foram poucas as vezes em que publicamos documentações sem colher os resultados desejados, justamente porque as escrevemos sem a devida empatia com os nossos clientes.

Aprendemos a lição: só produz documentações funcionais aquele que, de fato, se encarrega de ser empático para entender todos os casos de uso do produto para além de um único ponto de vista.

A empatia é um exercício diário que nos auxilia, até hoje, no entendimento profundo do produto e de seus usuários, assim como na identificação de quais tarefas devem ser priorizadas a partir do impacto que elas terão no desenvolvimento da empresa.

Priorização para gerar impacto

• 

Quando damos o primeiro passo de uma longa jornada, é comum pensarmos mais no destino final do que no ponto de partida.

Por essa lógica, colocamos altas expectativas na entrega rápida de valor aos usuários, muitas vezes ignorando o esforço necessário que pede a construção e execução de um backlog que seja de fato relevante para os leitores da futura documentação.

Um erro corriqueiro da VTEX foi tentar planejar um backlog que contemplasse o desafio extenso diante de nós. Sem grande surpresa, acabamos entregando pouco impacto e nos perdendo diante das tantas tarefas a serem executadas.

Não se engane: um backlog extenso não necessariamente representa as principais lacunas de documentação de um produto. Muitas vezes, ele é apenas resultado das múltiplas demandas (com os mais variados níveis de urgência) que surgem de todos os lados nesta etapa inicial da jornada.

Não aceitar passivamente todas as demandas de documentação foi uma das viradas de chave mais importantes para o nosso time. A partir disso, entendemos por conta própria onde moravam as maiores oportunidades de impacto, identificamos quais tarefas as refletiam de fato e, por fim, usamos a documentação como ferramenta para gerar resultados concretos na produção de conhecimento da empresa.

Integração para escalar esforços

• 

Se você só se preocupar em preencher lacunas, é possível que elas nunca deixem de existir! E eu diria que essa é a nossa principal lição aprendida.

O produto se reinventa diariamente e, assim, novas demandas chegam incessantemente até nós: como acompanhar, então, o ritmo acelerado da documentação? Com um time reduzido de tech writers e um desafio imenso diante de nós, apostamos em processos bem integrados com o time de desenvolvimento para escalar esforços, traduzidos em:

• Iniciativas colaborativas de documentação, como docathons — maratonas de força-tarefa em que desenvolvedores engajados com a frente de documentação se reúnem para atualizar documentações mais antigas ou criar novas do zero.
• Fluxos de trabalho confluentes entre tech writers e desenvolvedores, garantindo que as novas funcionalidades e atualizações sejam sempre identificadas e documentadas antes do momento do deploy.
• Padronização de novas documentações em templates, como este README que adotamos como ponto de partida para apps de React da VTEX. O uso de um bom template de documentação suporta o processo independente de escrita dos desenvolvedores durante o fluxo de trabalho e, consequentemente, a posterior revisão por parte dos technical writers.

Investir na integração com o time de desenvolvimento e no entendimento desse último da importância da documentação acelera resultados e intensifica seus impactos.

Nos dois últimos anos, encaramos uma verdadeira revolução na documentação da VTEX a partir, principalmente, da inclusão de tech writers no dia a dia do time do desenvolvimento e no comprometimento desse último em ressignificar a cultura de documentação e o Definition of Done do produto. O que antes era negligenciado se tornou regra clara: sem documentação, sem deploy.

Divulgação para garantir consistência

• 

Como as pessoas devem procurar apoio em documentações cuja existência elas ainda não sabem a respeito?

Na pressa de entregar valor aos usuários do produto, nos preocupamos apenas com a quantidade de documentações escritas e nos esquecemos de comunicar o que já foi publicado, isso é, o que já se encontra acessível para consulta.

Por muitos anos, o time VTEX seguiu forte na empreitada de produzir novas documentações, mas sem refletir sobre a necessária divulgação delas. O resultado, hoje compreensível, foi amargo para gente à época: poucos acessos em conteúdos que nos exigiram grandes esforços.

Aprendemos pelo erro a seguinte lição: a divulgação de novas documentações, ou até mesmo de importantes updates em documentações antigas, gera:

• Transparência sobre o trabalho de tech writers.
• Acessos em documentações já publicadas.
• Feedbacks valiosos dos usuários para a melhoria das documentações.

A partir disso, apostamos em formatos claros de comunicação, como release notes, e em canais amplos de interação, como o Slack. Não tardou muito para colhermos os resultados férteis listados acima, devido ao consumo real das nossas documentações pelos nossos clientes.

Independente do formato e canal escolhidos, o mais importante é não cair no erro corriqueiro de publicar sem posterior divulgação. Lembre-se: uma nova documentação funciona essencialmente como um novo produto digital da empresa – se ninguém sabe, ninguém usa!

Abrace a jornada infinita de documentar

Para qualquer caminho inédito da vida, o primeiro passo é sempre o mais desafiador. A insegurança de não conseguirmos avançar perdura até, de fato, nos equilibrarmos de pé e arriscarmos o primeiro movimento.

Como era de se esperar, a VTEX arriscou. Nos comprometemos a mudar o nosso paradigma de documentação e investimos pesado na mudança seguindo os nossos princípios: Trust to be trusted, Build for community, e Be bold. Hoje, satisfeitos com cada passo dado até aqui, compartilhamos os principais aprendizados da nossa jornada ainda em curso.

Ainda em curso, porque o fim dela não existe. A linha de chegada dessa maratona é, na verdade, uma ilusão: quanto mais você escrever, mais ficará distante. E está tudo bem!

Os produtos digitais estão em constante evolução e, consequentemente, também as suas respectivas documentações. A única certeza é a mudança, o esforço é contínuo. Faça as pazes com a instabilidade e a celebre — a infinitude da jornada de documentação nada mais é do que reflexo puro do crescimento acelerado de uma empresa!

O Tech Writer é aquele responsável por toda documentação técnica dos produtos digitais de uma empresa. Se interessou pela carreira? Confira as vagas abertas da VTEX e venha fazer parte do nosso time! careers.vtex.com