Diátaxis como um guia para o trabalho

Além de fornecer um guia para o conteúdo da documentação, o Diátaxis também é um guia para o processo e a execução da documentação.

A maioria das pessoas que trabalha com documentação técnica precisa tomar decisões sobre como trabalhar enquanto trabalha. Em alguns contextos, a documentação deve ser entregue uma única vez, completa e em seu estado final, mas é mais comum que seja um projeto contínuo, desenvolvido, por exemplo, juntamente com um produto que também evolui e se desenvolve. É também a experiência de muitas pessoas que trabalham com documentação verem-se responsáveis por melhorar ou até mesmo recuperar um conjunto de trabalhos.

O Diátaxis fornece uma abordagem de trabalho que vai contra grande parte da sabedoria convencional sobre documentação. Em particular, ele desencoraja o planejamento e fluxos de trabalho de cima para baixo (top-down), preferindo, em vez disso, pequenas iterações responsivas a partir das quais surgem padrões gerais.

Use o Diátaxis como um guia, não um plano

O Diátaxis descreve uma visão completa da documentação. No entanto, a estrutura que ele propõe não se destina a ser um plano, algo que você deve concluir na sua documentação. É um guia, um mapa para ajudar você a verificar se está no lugar certo e seguindo nas direções corretas.

O objetivo do Diátaxis é dar a você uma forma de pensar e compreender sua documentação, para que possa entender melhor o que ela está fazendo e o que você está tentando fazer com ela. Ele fornece ferramentas que ajudam a avaliá-la, a identificar onde estão seus problemas e a julgar o que você pode fazer para melhorá-la.

Não se preocupe com a estrutura

Embora estrutura seja fundamental para a documentação, usar o Diátaxis significa não gastar energia tentando deixar sua estrutura correta.

Se você continuar seguindo as orientações que o Diátaxis fornece, eventualmente sua documentação assumirá a estrutura do Diátaxis — mas ela terá assumido esse formato porque foi melhorada. Não é o contrário, que a estrutura deva ser imposta à documentação para melhorá-la.

Começar a usar o Diátaxis não exige que você pense em dividir sua documentação em quatro seções. Certamente não significa que você deve criar estruturas vazias para tutoriais/guias práticos/referência/explicação sem nada dentro. Não faça isso. É horrível.

Em vez disso, seguindo o fluxo de trabalho descrito nas próximas duas seções, faça alterações onde vir oportunidades de melhoria de acordo com os princípios do Diátaxis, de modo que a documentação comece a tomar uma determinada forma. A partir de certo ponto, as alterações feitas parecerão exigir que você mova o material para sob um determinado cabeçalho do Diátaxis — e é assim que a sua estrutura de nível superior se formará. Em outras palavras, o Diátaxis altera a estrutura da sua documentação a partir de dentro.

Trabalhe um passo de cada vez

O Diátaxis prescreve fortemente uma estrutura, mas qualquer que seja o estado da sua documentação existente — mesmo que seja uma bagunça completa sob qualquer aspecto —, sempre é possível melhorá-la, iterativamente.

É natural querer concluir grandes parcelas de trabalho antes de publicá-las, para que você tenha algo substancial para mostrar a cada vez. Evite essa tentação — cada passo na direção certa vale a pena ser publicado imediatamente.

Embora o Diátaxis se destine a fornecer uma visão geral da documentação, não tente trabalhar na visão geral. Isso é desnecessário e inútil. O Diátaxis foi projetado para guiar pequenos passos; continue dando pequenos passos para chegar onde deseja.

Apenas faça alguma coisa

Se você estiver organizando uma bagunça enorme, a tentação é derrubar tudo e começar de novo. Novamente, evite isso. No que diz respeito a melhorar a documentação em alinhamento com o Diátaxis, não é necessário procurar coisas para melhorar. Em vez disso, a melhor maneira de aplicar o Diátaxis é a seguinte:

Escolha algo - qualquer parte da documentação. Se você já não tiver algo que saiba que deseja corrigir, não saia procurando problemas pendentes. Apenas olhe para o que você tem bem na sua frente naquele momento: o arquivo em que você está, a última página que leu — não importa. Se não houver nenhum, escolha algo literalmente ao acaso.

Avalie. Em seguida, considere essa coisa de forma crítica. De preferência, deve ser algo pequeno, nada maior que uma página — ou melhor, ainda menor, um parágrafo ou uma frase. Questione isso de acordo com os padrões que o Diátaxis prescreve: Qual necessidade do usuário é representada por isso? Quão bem ela atende a essa necessidade? O que pode ser adicionado, movido, removido ou alterado para atender melhor a essa necessidade? Sua linguagem e lógica atendem aos requisitos deste modo de documentação?

Decide o que fazer. Decida com base nas suas respostas a essas perguntas: Qual próxima ação única produzirá uma melhoria imediata aqui?

Faça. Conclua essa próxima ação única e considere-a concluída — ou seja, publique-a ou, pelo menos, faça o commit da alteração. Não sinta que precisa fazer mais nada para realizar uma melhoria válida.

E então volte ao início do ciclo.

Trabalhar dessa forma ajuda a reduzir o estresse de um dos aspectos mais paralisantes e problemáticos do trabalho do redator de documentação: descobrir o que fazer. Isso mantém o trabalho fluindo na direção certa, sempre em direção ao fim desejado, sem ter que gastar energias em um plano.

Permita que seu trabalho se desenvolva organicamente

Há um forte impulso de trabalhar em um ciclo de planejamento e execução para avançar em direção aos resultados. Mas essa não é a única maneira, e muitas vezes existem maneiras melhores ao trabalhar com documentação.

Crescimento orgânico bem formado

Um bom modelo para a documentação é o crescimento orgânico bem formado que se adapta às condições externas. O crescimento orgânico ocorre no nível celular. A estrutura do organismo como um todo é garantida pelo desenvolvimento saudável das células, de acordo com as regras apropriadas para cada tipo de célula. Não é o contrário, que uma estrutura seja imposta ao organismo por cima ou de fora. Uma boa estrutura se desenvolve a partir de dentro.

Direitos autorais da ilustração Linette Voller 2021, reproduzido com a devida permissão.

O mesmo ocorre com a documentação: seguindo os princípios que o Diátaxis fornece, sua documentação alcançará uma estrutura saudável, porque seus próprios componentes internos são bem formados — como um organismo vivo, ela terá se construído de dentro para fora, uma célula de cada vez.

Completo, não finalizado

Considere uma planta. Como um organismo vivo e em crescimento, uma planta nunca está finalizada — ela sempre pode se desenvolver mais, passar para o próximo estágio de crescimento e maturação. Mas, em cada estágio de seu desenvolvimento, de uma semente a uma árvore totalmente madura, ela está sempre completa — nunca há algo faltando nela. Em qualquer ponto, ela está em um estado apropriado para seu estágio de desenvolvimento.

De forma semelhante, a documentação também nunca está finalizada, pois ela sempre precisa continuar se adaptando e mudando de acordo com o produto e as necessidades dos usuários, e sempre pode ser desenvolvida e melhorada ainda mais.

Contudo, ela sempre pode estar completa: útil para os usuários, apropriada para o seu estágio atual de desenvolvimento e em um estado estrutural saudável, pronta para prosseguir para o próximo estágio.