Skip to main content

A diferença entre reference e explanation

Explanation e reference pertencem à metade de teoria do mapa do Diátaxis — eles não contêm etapas para orientar o leitor, mas sim conhecimento teórico.

A diferença entre eles é — assim como na diferença entre tutoriais e how-to guides — 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 maior parte das vezes​

Na maioria das vezes, é bastante simples reconhecer se você está lidando com um ou com outro. Reference, como forma de escrita, é bem compreendido; é utilizado em distinções que fazemos sobre a escrita desde cedo.

Além disso, exemplos de textos costumam ser claramente um ou outro. Uma carta náutica, com suas tabelas de números, é claramente material de reference. Um artigo que explica por que existem marés e como elas se comportam é, por definição, explanation.

Há boas regras práticas:

  • Se for entediante e esquecível, provavelmente é reference.

  • Listas de itens (como classes, métodos ou atributos) e tabelas de informações geralmente pertencerão a reference.

  • Por outro lado, se você consegue imaginar a leitura de algo na banheira, provavelmente é explanation (ainda que não haja como prever o que as pessoas podem ler na banheira).

Imagine perguntar a um amigo, durante uma caminhada ou tomando uma bebida: Você pode me explicar mais sobre <topic>? — a resposta ou discussão resultante será muito provavelmente uma explanation sobre o assunto.

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

Na maior parte das vezes, podemos confiar com segurança na intuição para gerenciar a distinção entre reference e explanations. Mas apenas na maior parte das vezes — pois também é bastante fácil transitar de uma forma para a outra.

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

Como resultado, frequentemente encontra-se material explicativo intercalado no reference. Isso é prejudicial para o reference, que fica interrompido e obscurecido por digressões. Mas também é prejudicial para a explanation, pois ela não tem permissão para se desenvolver adequadamente e cumprir seu próprio papel.

Trabalho e estudo​

O verdadeiro teste, contudo, caso haja dúvidas se algo deve ser reference ou explanation, é: este é um conteúdo ao qual alguém recorreria durante o trabalho, ou seja, enquanto está de fato realizando algo, executando uma tarefa? Ou é algo de que precisaria após se afastar do trabalho, quando deseja refletir sobre ele?

Estas são duas necessidades fundamentalmente distintas do leitor, que refletem como, naquele momento, o leitor se posiciona em relação à prática em questão, em uma relação de trabalho ou estudo.

Reference é o que o usuário precisa para ajudar a aplicar conhecimento e habilidade enquanto trabalha.

Explanation é a que alguém recorrerá para ajudar a adquirir conhecimento e habilidade — o "estudo".

Compreender essas duas relações e atender às suas necessidades é a chave para criar reference e explanation eficazes.