Fundamentos

O Diátaxis é bem-sucedido porque funciona - como resultado, tanto os usuários quanto os criadores têm uma experiência melhor com a documentação. Faz sentido e parece correto.

No entanto, isso não é suficiente para confiar no Diátaxis como uma teoria da documentação. Como teoria, ele precisa mostrar o porquê de funcionar. Ele precisa mostrar que realmente existe alguma razão para haver exatamente quatro tipos de documentação, e não três ou cinco. Ele precisa demonstrar um pensamento e uma análise rigorosos, e que se apoia em uma base teórica sólida.

Caso contrário, será apenas mais uma abordagem heurística útil, e a afirmação mais forte que poderemos fazer sobre ele é que “parece funcionar muito bem”.

Duas dimensões do ofício

O Diátaxis baseia-se no princípio de que a documentação deve atender às necessidades de seus usuários. Saber como fazer isso significa entender quais são as necessidades dos usuários.

O usuário cujas necessidades o Diátaxis atende é o praticante em um domínio de habilidade. Um domínio de habilidade é definido por um ofício - o uso de uma ferramenta ou produto é um ofício. O mesmo vale para uma disciplina ou profissão inteira. Usar uma linguagem de programação é um ofício, assim como pilotar uma aeronave específica, ou até mesmo ser um piloto em geral.

Entender as necessidades desses usuários significa, por sua vez, entender as características essenciais do ofício ou da habilidade.

Ação/cognição

Uma habilidade, ofício ou prática contém tanto ação (conhecimento prático, saber como, o que fazemos) quanto cognição (conhecimento teórico, saber que, o que pensamos). Ambos estão completamente interligados, mas são contrapartes, totalmente distintos um do outro, dois aspectos diferentes da mesma coisa.

Aquisição/aplicação

Da mesma forma, a relação de um praticante com a sua prática é a de algo que precisa ser tanto adquirido quanto aplicado. Estar “no trabalho” (preocupado em aplicar a habilidade e o conhecimento do seu ofício) e estar “no estudo” (preocupado em adquiri-los) são novamente contrapartes, distintas mas interligadas.

O mapa do território

Isso nos dá duas dimensões da habilidade, que podemos dispor em um mapa - um mapa do território do ofício:

Este é um mapa completo. Existem apenas duas dimensões, e elas não apenas cobrem todo o território, elas o definem. É por isso que existem necessariamente quatro quadrantes nele, e não poderia haver três ou cinco. Não é um número arbitrário.

Ele também nos mostra as qualidades do ofício que definem cada um deles. Quando a ideia de que a documentação deve atender às necessidades do ofício é aplicada a este mapa, ela revela, por sua vez, o que a documentação deve ser e fazer para cumprir essas obrigações - de quatro maneiras distintas.

Atendendo às necessidades

O mapa do território do ofício é o que nos dá o familiar mapa de documentação do Diátaxis. O mapa é, na verdade, uma resposta à pergunta: o que a documentação deve fazer para se alinhar com essas qualidades da habilidade, e a qual necessidade ela se orienta em cada caso?

Podemos ver como o mapa de documentação aborda as necessidades ao longo dessas duas dimensões, com cada necessidade também definida pelas características de seu quadrante no mapa.

necessidade	abordada em	o usuário	a documentação
aprendizado	tutoriais	adquire seu ofício	informa a ação
objetivos	guias de como fazer	aplica seu ofício	informa a ação
informação	referência	aplica seu ofício	informa a cognição
compreensão	explicação	adquire seu ofício	informa a cognição

O mapa de documentação do Diátaxis é uma ideia memorável e acessível. Mas um mapa só é confiável se descrever adequadamente uma realidade. O Diátaxis é sustentado por uma descrição e análise sistemática das necessidades generalizadas do usuário.

É por isso que os tutoriais, guias de como fazer, referência e explicação do Diátaxis são uma enumeração completa dos tipos de documentação que atendem aos praticantes de um ofício. É por isso que existem quatro e apenas quatro tipos de documentação. Simplesmente não há outro território a cobrir.