Foundations

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

No entanto, isso não é suficiente para termos confiança no Diátaxis como uma teoria de documentação. Como teoria, ele precisa mostrar por que funciona. Ele precisa mostrar que realmente existe um motivo para haver exatamente quatro tipos de documentação, e não três ou cinco. Ele precisa demonstrar pensamento e análise rigorosos, e que se sustenta sobre uma base teórica sólida.

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

Duas dimensões do ofício

O Diátaxis é baseado 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 profissional 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 se aplica a uma disciplina ou profissão inteira. Usar uma linguagem de programação é um ofício, assim como pilotar uma aeronave específica, ou mesmo ser um piloto em geral.

Compreender as necessidades desses usuários significa, por sua vez, entender as características essenciais do ofício ou 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 atrelados um ao outro, mas são contrapartes, totalmente distintos entre si, dois aspectos diferentes da mesma coisa.

Aquisição/aplicação

Da mesma forma, a relação de um profissional com sua prática é que ela é algo que precisa ser tanto adquirida quanto aplicada. Estar “em trabalho” (preocupado em aplicar a habilidade e o conhecimento de seu ofício) e estar “em estudo” (preocupado em adquiri-los) são, mais uma vez, contrapartes, distintas, mas atreladas uma à outra.

O mapa do território

Isso nos dá duas dimensões de 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, mas o definem. É por isso que ele tem necessariamente quatro quadrantes, e não poderia ter 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 a 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 prática, uma resposta à pergunta: o que a documentação deve fazer para se alinhada a essas qualidades de habilidade e a qual necessidade ela se orienta em cada caso?

Podemos ver como o mapa de documentação aborda as necessidades nessas duas dimensões, sendo 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	guia práticos	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 descreve adequadamente a realidade. O Diátaxis é sustentado por uma descrição e análise sistemáticas de necessidades dos usuários generalizadas.

É por isso que os tutoriais, guias práticos, referências e explicações do Diátaxis constituem uma enumeração completa dos tipos de documentação que atendem aos profissionais em um ofício. É por isso que existem quatro, e apenas quatro, tipos de documentação. Simplesmente não há outro território a ser coberto.