Referência
Guias de referência são descrições técnicas do maquinário e como operá-lo. O material de referência é voltado para a informação.
O material de referência contém conhecimento proposicional ou teórico que um usuário consulta em seu trabalho.
O único propósito de um guia de referência é descrever, da forma mais sucinta possível e de maneira ordenada. Enquanto o conteúdo dos tutoriais e guias de como fazer é liderado pelas necessidades do usuário, o material de referência é liderado pelo produto que ele descreve.
No caso do software, os guias de referência descrevem o próprio software — APIs, classes, funções e assim por diante — e como utilizá-los.
Seus usuários precisam de material de referência porque precisam de verdade e certeza — plataformas firmes sobre as quais se apoiar enquanto trabalham. Uma boa referência técnica é essencial para fornecer aos usuários a confiança necessária para realizar seu trabalho.
Referência como descrição
O material de referência descreve o maquinário. Ele deve ser austero. Quase não se lê material de referência; a gente o consulta.
Não deve haver dúvida ou ambiguidade na referência; ela deve ser totalmente autoritativa.
O material de referência é como um mapa. Um mapa diz o que você precisa saber sobre o território, sem ter que sair e verificar o território por si mesmo; um guia de referência serve ao mesmo propósito para o produto e seu maquinário interno.
Embora a referência não deva tentar mostrar como realizar tarefas, ela pode e muitas vezes precisa incluir uma descrição de como algo funciona ou a maneira correta de usá-lo.
Alguns materiais de referência (como a documentação de API) podem ser gerados automaticamente pelo software que descrevem, o que é uma maneira poderosa de garantir que ele permaneça fielmente fiel ao código.
Princípios fundamentais
Descreva e apenas descreva
Descrição neutra é o imperativo fundamental da referência técnica.
Infelizmente, uma das coisas mais difíceis de fazer é descrever algo de forma neutra. Não é uma forma natural de se comunicar. O que é natural, por outro lado, é explicar, instruir, discutir, opinar, e todas essas coisas vão contra as necessidades da referência técnica, que exige precisão, exatidão, completude e clareza.
Pode ser tentador introduzir instruções e explicações, simplesmente porque a descrição pode parecer inadequada para ser útil e porque realmente precisamos dessas outras coisas. Em vez disso, faça links para guias de como fazer, explicações e tutoriais introdutórios.
Adote padrões estabelecidos
O material de referência é útil quando é consistente. Padrões estabelecidos são o que nos permite usar o material de referência de forma eficaz. Seu trabalho é colocar o material de que seu usuário precisa onde ele espera encontrá-lo, em um formato com o qual ele esteja familiarizado.
Existem muitas oportunidades na escrita para encantar seus leitores com seu extenso vocabulário e domínio de múltiplos estilos, mas o material de referência definitivamente não é uma delas.
Respeite a estrutura do maquinário
A forma como um mapa corresponde ao território que representa nos ajuda a usar o primeiro para encontrar nosso caminho através do segundo. Deve ser o mesmo com a documentação: a estrutura da documentação deve espelhar a estrutura do produto, para que o usuário possa trabalhar em ambos ao mesmo tempo.
Isso não significa forçar a documentação a uma estrutura não natural. O que é importante é que a organização conceitual lógica e as relações dentro do código ajudem a dar sentido à documentação.
Forneça exemplos
Exemplos são formas valiosas de fornecer ilustrações que ajudam os leitores a entender a referência, evitando o risco de se distrair do trabalho de descrição. Por exemplo, um exemplo de uso de um comando pode ser uma maneira sucinta de ilustrá-lo e seu contexto, sem cair na armadilha de tentar explicar ou instruir.
A linguagem dos guias de referência
A configuração de logging padrão do Django herda os padrões do Python. Está disponível como django.utils.log.DEFAULT_LOGGING e definida em django/utils/log.py.
Declare fatos sobre o maquinário e seu comportamento.
Os subcomandos são: a, b, c, d, e, f.
Liste comandos, opções, operações, recursos, flags, limitações, mensagens de erro, etc.
Você deve usar a. Você não deve aplicar b a menos que c. Nunca d.
Forneça avisos onde for apropriado.
Aplicado a comida e culinária
Você pode verificar as informações em uma embalagem de alimento para ajudá-lo a tomar uma decisão sobre o que fazer.
Quando você está procurando por informações — fatos relevantes —, você não quer ser confrontado com opiniões, especulações, instruções ou interpretações.
Você também espera que essas informações sejam apresentadas de maneiras padronizadas, para que você — quando precisar saber sobre as propriedades nutricionais de algo, como deve ser armazenado, seus ingredientes, quais implicações para a saúde pode ter — possa encontrá-las rapidamente e saber que pode confiar nelas.
Portanto, você espera ver, por exemplo: Pode conter traços de trigo. Ou: Peso líquido: 1000g.
Você certamente não esperará encontrar, por exemplo, receitas ou alegações de marketing misturadas com essas informações; isso poderia ser literalmente perigoso.
A forma como o material de referência é apresentado nos produtos alimentícios é tão importante que geralmente é regulada por lei, e o mesmo tipo de seriedade deve ser aplicado a toda a documentação de referência.