Explicação
A explicação é um tratamento discursivo de um assunto que permite a reflexão. A explicação é voltada para o entendimento.
A explicação aprofunda e amplia o entendimento 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 de outra coisa, 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 mais ampla do que a dos outros três tipos. Ela não adota a visão do nível dos olhos do usuário, como em um guia de como fazer, ou uma visão detalhada do maquinário, como o material de referência. Seu escopo em cada caso é um tópico — "uma área de conhecimento", que de alguma forma deve 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 enquanto se está longe do próprio produto (poderíamos dizer que a explicação é o único tipo de documentação que pode fazer sentido ler na banheira).
O valor e o lugar da explicação
Explicação e entendimento
A explicação é caracterizada pela sua distância das preocupações ativas do profissional. Ela não tem implicações diretas sobre o que eles fazem ou sobre seu trabalho. Isso significa que às vezes ela é vista como sendo de menor importância. Esse é um erro; ela pode ser menos urgente que as outras três, 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 ajudará a tecê-lo.
A palavra explicação — e seus cognatos em outros idiomas — refere-se a desdobrar, a revelação do que está oculto nas dobras. Assim, a explicação traz à luz coisas que estavam implícitas ou obscurecidas.
Da mesma forma, as palavras que significam entendimento compartilham raízes em palavras que significam segurar ou agarrar (como em compreender). Essa é uma parte importante do entendimento, ser capaz de segurar algo ou estar de posse dele. O entendimento sela os outros componentes do nosso domínio de um ofício e o torna com segurança nosso.
O entendimento não vem da explicação, mas a explicação é necessária para formar aquela teia que ajuda a manter tudo unido. Sem ela, o conhecimento do profissional sobre seu ofício é solto, fragmentado e frágil, e seu exercício dele é ansioso.
A explicação e seus limites
Muitas vezes a explicação não é explicitamente reconhecida na documentação; e a ideia de que as coisas precisam ser explicadas costuma ser expressa de forma fraca. Em vez disso, a explicação tende a ser espalhada em pequenas partes em outras seções.
Nem sempre é fácil escrever um bom material explicativo. Por onde começar? Também não está claro onde concluir. Há uma abertura que pode dar ao escritor opções demais.
Tutoriais, guias de como fazer e referência são todos claramente definidos em seu escopo por algo que também é bem definido: pelo que você precisa que o usuário aprenda, qual tarefa o usuário precisa realizar ou apenas pelo escopo da própria máquina.
No caso da explicação, é útil ter uma pergunta real ou imaginária de por que para servir como um guia. Caso contrário, você simplesmente tem que traçar algumas linhas que delimitam uma área razoável e se dar por satisfeito com isso.
Escrevendo uma boa explicação
Faça conexões
Ao escrever uma explicação, você está ajudando a tecer uma teia de entendimento para seus leitores. Faça conexões com outras coisas, mesmo com coisas fora do tópico imediato, se isso ajudar.
Forneça contexto
Forneça histórico e contexto em sua explicação: explique o porquê das coisas — decisões de design, razões históricas, restrições técnicas —, extraia 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) antes de cada título. Por exemplo: Sobre autenticação de usuário 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 humano são investidos em opinião, com crenças e pensamentos. A realidade de qualquer criação humana é rica em opinião, e isso precisa fazer parte de qualquer entendimento dela.
Da mesma forma, qualquer entendimento vem de uma perspectiva, um ponto de vista específico — o que significa que outros pontos de vista e perspectivas existem. A explicação pode e deve considerar alternativas, contraexemplos ou múltiplas abordagens diferentes para a mesma questão.
Na explicação, você não está dando instruções ou descrevendo fatos — você está abrindo o tópico para consideração. Ajuda pensar na explicação como uma discussão: discussões podem até considerar e pesar opiniões contrárias.
Mantenha a explicação estritamente delimitada
Um risco da explicação é que ela tende a absorver outras coisas. O escritor, com a intenção de cobrir o tópico, sente o desejo de incluir instruções ou descrições técnicas relacionadas a ele. Mas a documentação já possui outros lugares para isso, e permitir que eles se infiltrem interfere na própria explicação e os remove de exibição no local correto.
A linguagem da explicação
A razão para x é porque historicamente, y …
Explique.
W é melhor que z, porque …
Ofereça julgamentos e até opiniões onde for 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 (por causa de z). Esta pode ser uma boa abordagem, mas…
Pese as alternativas.
Um x interage com um y da seguinte forma: …
Revele os segredos internos do maquinário 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 (Sobre comida e culinária).
O livro não ensina como 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 culinária. Ele ilumina o assunto adotando múltiplas perspectivas diferentes sobre ele, lançando luz de diferentes ângulos.
Depois de ler um livro como On food and cooking, nosso entendimento muda. Nosso conhecimento é mais rico e profundo. O que aprendemos pode ou não ser imediatamente aplicável na próxima vez que estivermos fazendo algo na cozinha, mas mudará a forma como pensamos sobre o nosso ofício e afetará a nossa prática.