Clube do Livro VTEX: Decisões de documentação

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

Dentro do processo de documentação, tech writers tomam grandes decisões em relação a conteúdo e formato. Neste artigo, abordamos e discutimos as escolhas que tech writers realizam no dia a dia, apontadas pelo time de documentação do Splunk.

As decisões mais importantes são feitas quando você prioriza pedidos de documentação e quando você identifica o que documentar. (p.52)

Quem contribui para decisões de documentação?

Em uma empresa de tecnologia, principalmente em uma que o processo de documentação começou tardiamente, há uma inquietude para documentar todos os aspectos de um produto. Contudo, o tempo é um recurso limitado e nos exige priorizar determinadas documentações.

Dentro da área de documentação, o tech writer é responsável por decidir desde o que documentar até como documentar. Porém, apesar de dar o crivo final, não é apenas o tech writer que está envolvido nas decisões sobre documentação. Tais decisões envolvem pessoas de diversos contextos. Para determinar as prioridades da documentação, por exemplo, o technical writer deve agir em conjunto ao gerente de produto. Também é possível envolver technical writing managers para organizar os recursos necessários para o processo de documentação. Por fim, os editores do time podem contribuir com decisões de arquitetura da informação, voz e tom do texto.

Fatores relevantes para decisões de documentação

Para tomar decisões com embasamento, precisamos analisar os fatores relevantes que terão impacto direto sobre a documentação. São eles:

Público
Produto
Recursos
Documentação existente
Dados de uso
Feedback

Leia nas seções abaixo os detalhes de cada fator.

Público

É importante definir o que é um público dentro do contexto de Technical Writing - uma descrição geral de um grupo de pessoas que compõem o público. Identificar seu público é uma das decisões mais impactantes na documentação, pois o texto será desenvolvido e estruturado para ele. Por exemplo, é possível criar artigos mais conceituais e introdutórios para usuários mais iniciantes, e documentações mais complexas para usuários mais experientes.

Produto

A complexidade do produto influencia a documentação. Além disso, a frequência que sua empresa atualiza os seus produtos e o tempo que os clientes se adaptam a estas mudanças podem influenciar os tipos de decisões relativas à documentação - sobre o tipo de documentação e seu conteúdo.

Recursos

Considerar os recursos - equipe, tempo, ferramentas de escrita e publicação - dedicados para a documentação é vital quando se está tomando decisões. Não é possível decidir o que escrever, como escrever e quando escrever documentação sem saber quem e onde o fará.

O orçamento também se enquadra como recurso. As decisões que você toma sobre como é a documentação, onde você a hospeda, quantas pessoas vão escrevê-la e as ferramentas que você usa para criá-la são todas influenciadas por quanto dinheiro você tem à sua disposição.

Documentação existente

Documentação interna, feita pelos times de produto, auxilia no processo de tomar decisões sobre como escrever sua documentação. Quanto mais informação disponível você tiver sobre o produto - seja prioridades, o que foi feito e em qual ritmo - mais embasamento você terá para especular quando trabalhar em algo ou quanto tempo levará para ser concluído.

Dados de uso

Métricas do site de documentação ajudam a entender como as pessoas estão usando a documentação. Se os clientes visitam com frequência uma parte específica do produto, você pode priorizar o trabalho para documentar essas características do produto ou dar mais atenção a possíveis atualizações nesta seção da documentação. Quando estiver na dúvida em determinar no que trabalhar, os dados do produto podem ajudar a identificar quais características e funcionalidades do produto são mais utilizadas pelos clientes.

Feedback

O feedback é um recurso valioso para tomar decisões sobre documentação. O feedback do cliente pode ajudá-lo a entender quantas pessoas estão interessadas em melhorias para um tópico específico.

Tome uma decisão

No momento da tomada de decisão, leve em consideração os seguintes aspectos:

Defina a decisão que você precisa tomar.
Identifique os colaboradores para a decisão.
Identifique e analise os fatores relevantes para a decisão.

Defina a decisão que você precisa tomar

Faça a sua decisão ser a mais específica possível, descrevendo qual será o impacto dela para o seu negócio e seus clientes. Uma decisão específica facilita a análise dos fatores envolvidos.

Identifique os colaboradores para a decisão

Envolva outras pessoas no processo de decisão, principalmente gerentes de produto, designers e engenheiros para auxiliar nas prioridades da documentação.

Identifique os fatores relevantes para a decisão

Considere o tipo de informação que você precisa para tomar a decisão. Saiba quais informações já estão disponíveis e o que precisa ser levantado.

Analise os fatores relevantes para tomar a decisão

Use sua experiência e de seu time para analisar os dados coletados. Em seguida, aplique a informação mais relevante na sua decisão.

Documente e comunique sua decisão

Criar um planejamento de documentação é uma etapa importante para definir quais serão as decisões tomadas durante seu processo. O nível de detalhe de planejamento e informações variam de acordo com cada time e cada demanda. Uma boa prática é incluir um agendamento de tempo e documentar ao longo do processo quais decisões foram tomadas e suas justificativas.

Reduza as decisões que você precisa tomar

Foque nas decisões que realmente importam, não perca energia com pequenas decisões que não vão agregar valor à documentação. Para isso, priorize o que será documentado para ajudar a manter esse foco. Melhore suas decisões com um ciclo forte de feedback: estabeleça ciclos de feedbacks para melhorar seu embasamento nas decisões a partir da experiência dos usuários.

Citações

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

Citação	Página
Editores, se existirem no seu time, frequentemente contribuem para discussões sobre a arquitetura da informação, sobre a voz e o tom da documentação.	53
Um produto maduro provavelmente tem uma base de usuários robusta que espera um certo nível de detalhes ou estruturas na documentação.	54
Quanto mais informação você tiver sobre as prioridades dos times de engenharia, o que eles estão desenvolvendo, e quão completo esse trabalho é, mais você vai poder decidir trabalhar em algo ou quanto tempo você vai dedicar para fazê-lo.	56
Você pode usar métricas dos sites de documentação para ter melhor entendimento de como as pessoas estão utilizando-a.	57
(...) feedback do cliente pode ajudar você a entender quantas pessoas têm interesse nas melhorias de um tópico específico.	58
Quanto mais específica você tornar sua decisão, melhor.	59
Sempre descreva o impacto comercial e o resultado para o cliente. Quando sua decisão é mais específica, fica mais fácil para você considerar os fatores relevantes.	59
Muitas decisões são melhores se você trabalhar com outras pessoas.	59
Colete informações com os product managers, designers e engenheiros para te ajudar a tomar decisões sobre as prioridades de documentação.	59
Confie na expertise própria e do seu time, e nos resultados da análise de dados para que você possa coletar e aplicar informações relevantes à decisão que deseja tomar.	60