O mapa

Um dos motivos pelos quais o Diátaxis é eficaz como guia para organizar a documentação é que ele descreve uma estrutura bidimensional, em vez de uma lista.

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

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

O problema da estrutura

Quando a documentação falha em obter uma boa estrutura, raramente é apenas um problema de estrutura (embora seja ruim o suficiente para dificultar o uso e a manutenção). Falhas arquitetônicas também infectam e enfraquecem o conteúdo.

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

Isso raramente tem sucesso, mesmo em uma única instância. Em um portfólio de instâncias de documentação, os resultados são uma inconsistência drástica. Muito melhor é a adoção de um esquema que tente fornecer uma resposta à pergunta: como organizar a documentação em geral?

Na verdade, 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), fornecendo listas de tipos de conteúdo.

Ainda assim, os autores frequentemente se veem precisando escrever um conteúdo de documentação específico que não se encaixa bem nas categorias propostas por um esquema, ou lutando para reescrever o material existente. Frequentemente, há uma sensação de arbítrio sobre a estrutura com a qual acabam trabalhando — por que esta lista específica de tipos de conteúdo em vez de outra? E se outra lista concorrente for proposta, qual adotar?

Expectativas e orientações

Uma vantagem clara de organizar o material dessa maneira é que ele fornece tanto expectativas claras (para o leitor) quanto orientações (para o autor). Fica claro qual é o propósito de qualquer pedaço de conteúdo específico, especifica como ele deve ser escrito e mostra onde deve ser colocado.

	Tutoriais	Guia de instruções	Referência	Explicação
o que fazem	introduzem, educam, conduzem	orientam	constatam, descrevem, informam	explicam, esclarecem, discutem
responde à pergunta	“Você pode me ensinar a...?”	“Como eu 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
forma	uma lição	uma série de etapas	descrição seca	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 alimento	um artigo sobre história social culinária

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

Diluição

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, há um tipo de afinidade natural entre cada uma das diferentes formas de documentação e seus vizinhos no mapa, e uma tendência natural de diluir as distinções (que pode ser vista repetidamente em exemplos de documentação).

| guiar a ação | tutoriais | guias de instruções | | servir à aplicação de habilidade | referência | guias de instruções | | conter conhecimento proposicional | referência | explicação | | servir à aquisição de habilidade | tutoriais | explicação |

Quando essas distinções podem se diluir, os diferentes tipos de documentação se misturam. O estilo de escrita e o conteúdo acabam parando em lugares inadequados. Isso também causa problemas estruturais, que tornam ainda mais difícil manter a disciplina da escrita adequada.

No pior dos casos, ocorre um colapso total ou parcial de tutoriais e guias de instruções uns nos outros, tornando impossível atender às necessidades atendidas por qualquer um deles.

---

A jornada pelo mapa

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

Esta frase não deve ser entendida de forma muito literal. Não é verdade que um usuário deva encontrar os diferentes tipos de documentação na ordem tutoriais > guias de instruções > referência técnica > explicação. Na prática, um usuário real pode entrar na documentação em qualquer ponto em busca de orientações sobre algum assunto específico, e o que ele deseja ler mudará de um momento para o outro à medida que usa a documentação.

No entanto, a ideia de um ciclo de necessidades de documentação, que progride através de diferentes fases, é sólida e corresponde à maneira como as pessoas realmente se tornam especialistas em um ofício. Há sentido e significado nessa 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 conhecimento que ainda não temos em mente, precisamos consultar a referência técnica.

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

E então voltamos ao início, talvez para absorver algo novo ou para aprofundar o entendimento.