A diferença entre referência e explicação

A explicação e a referência pertencem à metade da teoria do mapa do Diátaxis - elas não contêm passos para guiar o leitor, mas contêm conhecimento teórico.

A diferença entre elas é - assim como na diferença entre tutoriais e guias de como fazer - a diferença entre a aquisição de habilidade e conhecimento e sua aplicação. Em outras palavras, é a distinção entre estudo e trabalho.

Uma distinção direta, na maioria das vezes

Na maioria das vezes, é bastante simples reconhecer se você está lidando com um ou outro. A referência, como forma de escrita, é bem compreendida; ela é usada em distinções que fazemos sobre a escrita desde a infância.

Além disso, os próprios exemplos de escrita são frequentemente e claramente um ou outro. Uma tábua de marés, com suas tabelas de números, é claramente um material de referência. Um artigo que explica por que existem marés e como elas se comportam é autoevidentemente uma explicação.

Existem boas regras práticas:

• Se for entediante e difícil de memorizar, provavelmente é referência.

• Listas de coisas (como classes, métodos ou atributos) e tabelas de informações geralmente pertencerão à referência.

• Por outro lado, se você consegue se imaginar lendo algo na banheira, provavelmente é explicação (mesmo que, na verdade, não haja como justificar o que as pessoas podem ler na banheira).

Imagine perguntar a um amigo, durante uma caminhada ou tomando um drink: Você pode me falar mais sobre <tópico>? - a resposta ou discussão que se segue provavelmente será uma explicação sobre o assunto.

... mas a intuição não é confiável o suficiente

Na maioria das vezes, podemos confiar com segurança na intuição para gerenciar a distinção entre referência e explicação. Mas apenas na maioria das vezes - porque também é muito fácil deslizar de uma forma para a outra.

Isso geralmente acontece ao escrever material de referência que começa a se tornar expansivo. Por exemplo, é perfeitamente razoável incluir exemplos ilustrativos na referência (assim como uma enciclopédia pode conter ilustrações) - mas os exemplos são divertidos de desenvolver, e pode ser tentador desenvolvê-los em explicações (usando-os para dizer por que, ou mostrar e se, ou como as coisas surgiram).

Como resultado, muitas vezes encontramos material explicativo espalhado na referência. Isso é ruim para a referência, que é interrompida e obscurecida por digressões. Mas também é ruim para la explicação, porque ela não tem espaço para se desenvolver adequadamente e fazer seu próprio trabalho.

Trabalho e estudo

O verdadeiro teste, no entanto, se tivermos dúvidas sobre se algo deve ser referência ou explicação, é: isso é algo a que alguém recorreria enquanto trabalha, ou seja, enquanto está realmente fazendo algo, executando uma tarefa? Ou é algo de que precisaria depois de se afastar do trabalho e querer pensar sobre isso?

Estas são duas necessidades do leitor fundamentalmente diferentes, que refletem como, naquele momento, o leitor se posiciona em relação ao ofício em questão, em uma relação de trabalho ou de estudo.

A referência é o que o usuário precisa para ajudar a aplicar conhecimento e habilidade enquanto está trabalhando.

A explicação é o que alguém buscará para ajudar a adquirir conhecimento e habilidade - o “estudo”.

Compreender essas duas relações e responder às necessidades contidas nelas é a chave para criar referências e explicações eficazes.