Diátaxis como guia de 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 de uma só vez, completa e em seu estado final, mas é mais comum que seja um projeto contínuo, por exemplo, desenvolvido junto com um produto que também evolui e se desenvolve. Também é a experiência de muitas pessoas que trabalham com documentação encontrar-se responsáveis por melhorar ou até remediar um conjunto de trabalhos.
O Diátaxis oferece uma abordagem de trabalho que vai na contramão de grande parte da sabedoria aceita em documentação. Em particular, desencoraja o planejamento e os workflows top-down, preferindo iterações pequenas e responsivas das quais emergem padrões gerais.
Use o Diátaxis como um guia, não como um plano
O Diátaxis descreve uma visão abrangente da documentação. No entanto, a estrutura que ele propõe não pretende ser um plano, algo que você deva concluir na sua documentação. É um guia, um mapa para ajudar a verificar se você está no lugar certo e indo na direção correta.
O objetivo do Diátaxis é fornecer uma forma de pensar e entender a sua documentação, para que você possa compreender melhor o que ela está fazendo e o que você está tentando fazer com ela. Ele fornece ferramentas que ajudam a avaliá-la, identificar onde estão seus problemas e julgar o que você pode fazer para melhorá-la.
Não se preocupe com a estrutura
Embora a estrutura seja fundamental para a documentação, usar o Diátaxis significa não gastar energia tentando acertar a sua estrutura .**
Se você continuar seguindo as diretrizes que o Diátaxis fornece, eventualmente a sua documentação assumirá a estrutura do Diátaxis - mas ela assumirá essa forma porque foi melhorada. Não é o contrário, ou seja, a estrutura não deve ser imposta à documentação para melhorá-la.
Começar a usar o Diátaxis não exige que você pense em dividir a sua documentação em quatro seções. Certamente não significa que você deva criar estruturas vazias para tutoriais/guias de como fazer/referência/explicação sem nada nelas. Não faça isso. É horrível.
Em vez disso, seguindo o workflow 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, para que a documentação comece a tomar uma determinada forma. Em um determinado ponto, as alterações feitas parecerão exigir que você mova material sob um determinado cabeçalho do Diátaxis - e é assim que sua estrutura de alto nível 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, seja qual for o estado da sua documentação existente - mesmo que seja um completo caos por qualquer padrão -, é sempre possível melhorá-la de forma iterativa.
É natural querer concluir grandes lotes de trabalho antes de publicá-los, para ter 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 tenha como objetivo fornecer uma visão geral da documentação, não tente trabalhar na visão geral. É tanto desnecessário quanto inútil. O Diátaxis foi projetado para guiar pequenos passos; continue dando pequenos passos para chegar onde você quer ir.
Apenas faça algo
Se você estiver organizando uma bagunça enorme, a tentação é derrubar tudo e começar de novo. Novamente, evite-a. 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ê ainda não tem algo que sabe que quer corrigir, não vá procurar 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-o. Em seguida, analise criticamente esse item. De preferência, que seja algo pequeno, nada maior do que uma página - ou, melhor ainda, menor, um parágrafo ou uma frase. Analise-o criticamente de acordo com os padrões prescritos pelo Diátaxis: Qual necessidade do usuário é representada por isso? Quão bem ele atende a essa necessidade? O que pode ser adicionado, movido, removido ou alterado para* atender melhor a essa necessidade? A linguagem e a lógica atendem aos requisitos deste modo de documentação?*
Decida o que fazer. Decida, com base nas suas respostas a essas perguntas: Qual única ação seguinte produzirá uma melhoria imediata aqui?
Faça isso. Conclua essa única ação seguinte, 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 digna.
E então retorne ao início do ciclo.
Trabalhar assim 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 precisar gastar energia com um plano.
Permita que seu trabalho se desenvolva organicamente
Há um forte impulso para trabalhar em um ciclo de planejamento e execução para alcançar 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 regras apropriadas para cada tipo de célula. Não é o contrário, ou seja, uma estrutura não é imposta ao organismo de cima ou de fora. Uma boa estrutura se desenvolve a partir de dentro.
Ilustração com direitos autorais de Linette Voller 2021, reproduzida com gentil permissão.
O mesmo acontece com a documentação: ao seguir os princípios fornecidos pelo Diátaxis, a sua documentação atingirá uma estrutura saudável, porque seus componentes internos são bemformados - como um organismo vivo, ela terá se construído de dentro para fora, uma célula de cada vez.
Completo, não acabado
Considere uma planta. Como um organismo vivo e em crescimento, uma planta nunca está acabada - ela pode sempre se desenvolver mais, passar para o próximo estágio de crescimento e maturidade. No entanto, em cada estágio de seu desenvolvimento, desde a semente até uma árvore totalmente madura, ela está sempre completa - nunca falta nada nela. A qualquer momento, ela está em um estado adequado ao seu estágio de desenvolvimento.
Da mesma forma, a documentação também nunca está acabada, porque precisa sempre continuar se adaptando e mudando em relação ao produto e às necessidades dos usuários, podendo sempre ser desenvolvida e melhorada ainda mais.
No entanto, ela pode estar sempre completa: útil para os usuários, adequada ao seu estágio atual de desenvolvimento, em um estado estrutural saudável e pronta para avançar para o próximo estágio.