Recordar Relembrar
Relembrar informações que não foi possível memorizar, desde parâmetros até códigos de erro.
Uma das coisas que mantém a documentação viva após anos e anos de utilização é o seu valor como material de referência. Percorremos as páginas dos manuais para recordar — relembrar, recuperar, procurar — informações que não conseguimos memorizar, desde parâmetros e códigos de erro até valores admissíveis.
Exemplos de documentação que responde à necessidade de recordar são a referência do Dockerfile da Docker e a referência da sintaxe YAML de CI/CD do GitLab. Ambos apresentam informações facilmente pesquisáveis e altamente estruturadas sobre os fragmentos que o utilizador precisa de relembrar para executar diversos encantamentos.
A documentação de referência é a base da usabilidade de um produto a longo prazo. Embora a documentação criada para satisfazer outras ações possa ser lida uma vez e assimilada, o material de referência conserva permanentemente o seu valor à medida que os utilizadores aprofundam os seus conhecimentos e enfrentam implementações cada vez mais sofisticadas.
O que o utilizador quer fazer
O material de referência mantém a documentação viva após anos de utilização. Os utilizadores consultam os manuais para recordar, relembrar, recuperar ou procurar informações que não conseguiram memorizar.
Sinais de que a documentação não responde a esta necessidade
- Os utilizadores procuram um parâmetro ou código de erro e não encontram nada.
- O material de referência está disperso por artigos de blogues e históricos de conversas.
- Não existe uma referência estruturada e pesquisável para a sintaxe ou as definições do produto.
Dois exemplos reais
Tipos de conteúdo comuns
| DITA | Diátaxis | Good Docs Project |
|---|---|---|
| <reference>, <refsyn>, <properties> | Referência | Referência, Glossário |
Uma métrica
taxa de sucesso das consultas · Percentagem das consultas ao material de referência que devolvem a página certa.