A bússola

O mapa do Diátaxis é um lembrete eficaz dos diferentes tipos de documentação e sua relação, e está bem alinhado com as intuições sobre documentação.

No entanto, a intuição nem sempre é confiável. Muitas vezes, ao trabalhar com documentação, um autor se depara com a pergunta: qual é a forma de documentação disto? ou que forma de documentação é necessária aqui? — e não há uma resposta óbvia e intuitiva.

Pior ainda, às vezes a intuição fornece uma resposta imediata que também está errada.

Um mapa é mais poderoso em território desconhecido quando também temos uma bússola para nos guiar.

A bússola do Diátaxis é algo como uma tabela verdade ou árvore de decisão da documentação. Ela reduz um problema bidimensional mais complexo a suas partes mais simples e fornece ao autor uma ferramenta de correção de curso.

Se o conteúdo…	…e serve à… do usuário	…então deve pertencer a…
informa a ação	aquisição de habilidade	um tutorial
informa a ação	aplicação de habilidade	um guia de como fazer
informa a cognição	aplicação de habilidade	referência
informa a cognição	aquisição de habilidade	explicação

A bússola pode ser aplicada igualmente a situações do usuário que necessitam de documentação, ou à própria documentação que talvez precise ser movida ou melhorada. Como muitas boas ferramentas, ela é surpreendentemente simples.

Para usar a bússola, basta fazer duas perguntas: ação ou cognição? aquisição ou aplicação?

E ela fornece a resposta.

Usando a bússola

A bússola é particularmente eficaz quando você pensa que você (ou mesmo a documentação à sua frente) está fazendo uma coisa — mas você está incomodado por uma sensação de dúvida, ou por alguma dificuldade no trabalho. A bússola força você a parar e reconsiderar.

Especialmente quando você estiver tentando encontrar suas direções iniciais, use os termos da bússola com flexibilidade; não fique fixado nos nomes exatos.

• ação: passos práticos, fazer

• cognição: conhecimento teórico ou proposicional, pensar

• aquisição: estudo

• aplicação: trabalho

E as próprias perguntas também podem ser usadas de diferentes maneiras:

• Eu acho que estou escrevendo para x ou y?

• Este texto à minha frente está envolvido com x ou y?

• O usuário precisa de x ou y?

• Eu quero fazer x ou y?

E tente aplicá-las de perto, ao nível de frases e palavras, ou de uma perspectiva mais ampla, considerando um documento inteiro.