O mapa

Uma das razões pelas quais o Diátaxis é eficaz como um guia para organizar documentação é que ele descreve uma estrutura bidimensional, em vez de uma lista.

Ele especifica seus tipos de documentação de tal forma que a estrutura ajuda naturalmente a guiar e moldar o material que contém.

Como um mapa, ele coloca as diferentes formas de documentação em relação umas com as outras. Cada uma ocupa um espaço no território mental que ele delineia, e os limites entre elas destacam suas distinções.

O problema da estrutura

Quando documentação falha em obter uma boa estrutura, raramente é apenas um problema de estrutura (embora isso já seja ruim o suficiente por tornar mais difícil de usar e manter). Falhas arquiteturais também afetam e enfraquecem o conteúdo.

Na ausência de uma arquitetura de documentação clara e generalizada, os criadores de documentação frequentemente tentarão estruturar seu trabalho em torno dos recursos (features) de um produto.

Isso raramente é bem-sucedido, mesmo em um único caso. Em um portfólio de instâncias de documentação, o resultado é uma inconsistência gritante. Muito melhor é a adoção de um esquema que tente responder à pergunta: como organizar a documentação em geral?

De fato, qualquer tentativa ordenada de organizar a documentação em categorias de conteúdo claras ajudará a melhorá-la (tanto para autores quanto para usuários), ao fornecer listas de tipos de conteúdo.

Ainda assim, os autores frequentemente se veem na necessidade de escrever conteúdos específicos de documentação que não se encaixam bem nas categorias propostas por um esquema, ou lutando para reescrever o material existente. Frequentemente, há uma sensação de arbitrariedade em relação à estrutura com a qual se veem trabalhando — por que esta lista específica de tipos de conteúdo em vez de outra? E se outra lista concorrente for proposta, qual delas adotar?

Expectativas e orientação

Uma vantagem clara de organizar o material dessa forma é que isso fornece tanto expectativas claras (para quem lê) quanto orientação (para quem escreve). Fica claro qual é o propósito de qualquer parte específica do conteúdo, especifica como deve ser escrito e mostra onde deve ser colocado.

	Tutoriais	Guias práticos	Referência	Explicação
o que fazem	introduzir, educar, liderar	guiar	declarar, descrever, informar	explicar, esclarecer, discutir
responde à pergunta	“Você pode me ensinar a...?”	“Como faço para...?”	“O que é...?”	“Por quê...?”
orientado a	aprendizado	objetivos	informação	compreensão
propósito	fornecer uma experiência de aprendizado	ajudar a alcançar um objetivo específico	descrever o maquinário	iluminar um tópico
formato	uma lição	uma série de passos	descrição objetiva	explicação discursiva
analogia	ensinar uma criança a cozinhar	uma receita em um livro de culinária	informações no verso de uma embalagem de comida	um artigo sobre história social da culinária

Cada parte do conteúdo é de um tipo que não apenas tem uma tarefa específica a cumprir, mas essa tarefa também é claramente distinguida e contrastada com as outras funções da documentação.

Desfoque

A maioria dos sistemas de documentação e autores reconhece pelo menos algumas dessas distinções e tenta observá-las na prática.

No entanto, existe uma espécie de afinidade natural entre cada uma das diferentes formas de documentação e as vizinhas no mapa, bem como uma tendência natural de desfoque das distinções (o que pode ser visto repetidamente em exemplos de documentação).

| guiar a ação | tutoriais | guias práticos | | serve à aplicação de habilidades | referência | guias práticos | | conter conhecimento proposicional | referência | explicação | | servir à aquisição de habilidades | tutoriais | explicação |

Quando essas distinções se tornam desfocadas, os diferentes tipos de documentação se misturam entre si. O estilo de escrita e o conteúdo acabam entrando em locais inadequados. Isso também causa problemas estruturais, o que torna ainda mais difícil manter a disciplina de uma escrita apropriada.

No pior caso, ocorre um colapso completo ou parcial de tutoriais e guias práticos entre si, impossibilitando o atendimento das necessidades supridas por ambos.

---

A jornada pelo mapa

O Diátaxis visa ajudar a documentação a servir melhor os usuários em seu ciclo de interação com um produto.

Esta frase não deve ser entendida de forma literal demais. Não é o caso que um usuário deva encontrar os diferentes tipos de documentação na ordem tutoriais > guias práticos > referência técnica > explicação. Na prática, um usuário real pode entrar na documentação por qualquer lugar em busca de orientação sobre algum assunto específico, e o que deseja ler mudará de momento a momento enquanto usa sua documentação.

No entanto, a ideia de um ciclo de necessidades de documentação que avança por diferentes fases é sólida e corresponde à forma como as pessoas realmente se tornam especialistas em um ofício. Existe um sentido e um significado para essa ordenação.

• fase orientada ao aprendizado: Começamos aprendendo, e aprender uma habilidade significa mergulhar direto na prática — sob a orientação de um professor, se tivermos sorte.

• fase orientada a objetivos: Em seguida, queremos colocar a habilidade em prática.

• fase orientada à informação: Assim que nosso trabalho exige um conhecimento que ainda não temos na cabeça, precisamos consultar a referência técnica.

• fase orientada à explicação: Finalmente, afastados do trabalho, refletimos sobre nossa prática e conhecimento para compreender o todo.

E então voltamos ao início, talvez para compreender algo novo ou para nos aprofundarmos ainda mais.