Explicação
A explicação é um tratamento discursivo de um assunto, que permite a reflexão. A explicação é orientada para a compreensão.
A explicação aprofunda e amplia a compreensão do leitor sobre um assunto. Ela traz clareza, luz e contexto.
O conceito de reflexão é importante. A reflexão ocorre após outra coisa e depende dela, mas ao mesmo tempo traz algo novo — lança uma nova luz — sobre o assunto em questão.
A perspectiva da explicação é mais alta e ampla do que a dos outros três tipos. Ela não adota a visão ao nível dos olhos do usuário, como em um guia prático, nem uma visão detalhada da engrenagem, como o material de referência. O seu escopo em cada caso é um tópico — "uma área de conhecimento", que de alguma forma precisa ser delimitada de maneira razoável e significativa.
Para o usuário, a explicação conecta as coisas. É uma resposta à pergunta: Você pode me falar sobre …?
É uma documentação que faz sentido ler longe do próprio produto (poderíamos dizer que a explicação é o único tipo de documentação que faz sentido ler no banho).
O valor e o lugar da explicação
Explicação e compreensão
A explicação caracteriza-se pela distância em relação às preocupações ativas do profissional. Ela não tem implicações diretas para o que ele faz ou para o seu trabalho. Isso significa que, às vezes, ela é vista como sendo de menor importância. Isso é um erro; ela pode ser menos urgente do que os outros três tipos, mas não é menos importante. Não é um luxo. Nenhum profissional de um ofício pode se dar ao luxo de ficar sem a compreensão desse ofício, e precisa do material explicativo que ajude a costurá-lo.
A palavra explicação — e seus cognatos em outros idiomas — refere-se ao desdobramento, à revelação do que está oculto nas dobras. Portanto, a explicação traz à luz coisas que estavam implícitas ou obscurecidas.
Da mesma forma, palavras que significam compreensão compartilham raízes em palavras que significam segurar ou agarrar (como em compreender). Essa é uma parte importante da compreensão: poder segurar algo ou estar de posse dele. A compreensão une os outros componentes do nosso domínio de um ofício e o torna com segurança nosso.
A compreensão não vem da explicação, mas a explicação é necessária para formar essa rede que ajuda a manter tudo unido. Sem ela, o conhecimento do profissional sobre o seu ofício é solto, fragmentado e frágil, e o seu exercício dele é angustiante.
A explicação e seus limites
Com bastante frequência, a explicação não é explicitamente reconhecida na documentação; e a ideia de que as coisas precisam ser explicadas costuma ser expressa apenas de forma sutil. Em vez disso, a explicação tende a ser dispersa em pequenas parcelas em outras seções.
Não é fácil escrever um bom material explicativo. Por onde começar? Também não está claro onde terminar. Há uma abertura nisso que pode dar ao escritor muitas possibilidades.
Tutoriais, guias práticos e referências têm seus escopos claramente definidos por algo que também é bem definido: pelo que você precisa que o usuário aprenda, pela tarefa que o usuário precisa realizar ou simplesmente pelo escopo da própria máquina.
No caso da explicação, é útil ter uma pergunta por que real ou imaginária para servir de estímulo. Caso contrário, você simplesmente precisa traçar algumas linhas que delimitam uma área razoável e ficar satisfeito com isso.
Escrevendo boas explicações
Faça conexões
Ao escrever explicações, você está ajudando a tecer uma rede de compreensão para os seus leitores. Faça conexões com outras coisas, até mesmo com coisas fora do tópico imediato, se isso ajudar.
Forneça contexto
Forneça histórico e contexto na sua explicação: explique por que as coisas são assim — decisões de design, razões históricas, restrições técnicas — tire implicações, mencione exemplos específicos.
Fale sobre o assunto
Os guias de explicação são sobre um tópico no sentido de que estão ao redor dele. Até mesmo os nomes dos seus guias de explicação devem refletir isso; você deve ser capaz de colocar um sobre implícito (ou mesmo explícito) na frente de cada título. Por exemplo: Sobre autenticação de usuários ou Sobre políticas de conexão com o banco de dados.
Admita opinião e perspectiva
A opinião pode parecer uma coisa estranha de se introduzir na documentação. O fato é que toda atividade e conhecimento humanos estão investidos de opinião, de crenças e pensamentos. A realidade de qualquer criação humana é rica em opiniões, e isso precisa fazer parte de qualquer compreensão dela.
Da mesma forma, qualquer compreensão vem de uma perspectiva, de um ponto de vista específico — o que significa que outras perspectivas e pontos de vista existem. A explicação pode e deve considerar alternativas, contra-exemplos ou várias abordagens diferentes para a mesma questão.
Na explicação, você não está dando instruções nem descrevendo fatos — você está abrindo o tópico para consideração. Ajuda pensar na explicação como uma discussão: as discussões podem até considerar e ponderar opiniões contrárias.
Mantenha a explicação rigidamente delimitada
Um risco da explicação é que ela tende a absorver outras coisas. O escritor, determinado a cobrir o tópico, sente o impulso de incluir instruções ou descrições técnicas relacionadas a ele. Mas a documentação já tem outros lugares para isso, e permitir que eles apareçam interfere na explicação em si e os remove de vista no lugar correto.
A linguagem da explicação
O motivo de x é porque, historicamente, y …
Explique.
W é melhor do que z, porque …
Ofereça julgamentos e até opiniões quando apropriado.
Um x no sistema y é análogo a um w no sistema z. No entanto …
Forneça contexto que ajude o leitor.
Alguns usuários preferem w (porque z). Esta pode ser uma boa abordagem, mas…
Pondere alternativas.
Um x interage com um y da seguinte forma: …
Desvende os segredos internos da máquina para ajudar a entender por que algo faz o que faz.
Analogia com comida e culinária
Em 1984, Harold McGee publicou On food and cooking.
O livro não ensina a cozinhar nada. Ele não contém receitas (exceto como exemplos históricos) e não é uma obra de referência. Em vez disso, ele coloca a comida e a culinária no contexto da história, da sociedade, da ciência e da tecnologia. Ele explica, por exemplo, por que fazemos o que fazemos na cozinha e como isso mudou.
Claramente não é um livro que leríamos enquanto cozinhamos. Nós o leríamos quando quiséssemos refletir sobre a culinária. Ele ilumina o assunto adotando múltiplas perspectivas diferentes sobre ele, brilhando luz de diferentes ângulos.
Depois de ler um livro como On food and cooking, nossa compreensão muda. Nosso conhecimento é mais rico e profundo. O que aprendemos pode ou não ser imediatamente aplicável da próxima vez que estivermos fazendo algo na cozinha, mas isso mudará a forma como pensamos sobre o nosso ofício e afetará a nossa prática.