Recordar Relembrar
Relembrar informações que não foi possível memorizar, de parâmetros a códigos de erro.
Uma das coisas que mantém a documentação viva depois de anos e anos de uso é 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, de parâmetros e códigos de erro a valores aceitáveis.
Exemplos de documentação que atende à necessidade de recordar são a referência do Dockerfile da Docker e a referência da sintaxe YAML de CI/CD do GitLab. Apresentam informações facilmente pesquisáveis e altamente estruturadas sobre os fragmentos que o usuário precisa relembrar para executar os seus vários encantamentos.
A documentação de referência é a base da usabilidade de um produto no longo prazo. Embora a documentação criada para atender a outras ações possa ser lida uma vez e assimilada, o material de referência mantém o seu valor permanentemente à medida que os usuários aprofundam os seus conhecimentos e enfrentam implementações cada vez mais sofisticadas.
O que o usuário quer fazer
O material de referência mantém a documentação viva depois de anos de uso. Os usuários consultam manuais para recordar, relembrar, recuperar ou procurar informações que não conseguiram memorizar.
Sinais de que a documentação não atende a essa necessidade
- Os usuários procuram um parâmetro ou código de erro e não encontram nada.
- O material de referência está espalhado por posts de blog e históricos de conversas.
- Não existe uma referência estruturada e pesquisável para a sintaxe ou as configuraçõ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 acerto das consultas · Proporção das consultas ao material de referência que retornam a página certa.