Redação técnica

Documentação escrita a partir do produto, não da especificação

A maior parte da documentação má foi escrita a partir de um documento de requisitos ou da memória de um programador. Descreve como a funcionalidade devia funcionar, não o ecrã que o utilizador vê de facto, com o seu botão renomeado e o seu passo de confirmação extra. O utilizador segue o passo quatro, não encontra nada correspondente e abre um ticket.

Executamos todos os procedimentos do produto antes de os documentar, numa conta de teste, no papel que o leitor terá. Quando um passo se comporta de forma diferente do que a equipa espera, registamo-lo, porque o trabalho de documentação revela rotineiramente erros que ninguém tinha reportado. Essa lista acaba muitas vezes por valer tanto como a documentação.

Separar a tarefa da explicação

Um utilizador que tenta exportar uma fatura não quer três parágrafos sobre o modelo de faturação primeiro. Um utilizador que tenta compreender o modelo de faturação não quer uma lista numerada de cliques. Misturar os dois num só artigo torna ambos mais difíceis de encontrar e mais lentos de ler.

Dividimos o conteúdo em tarefas (como fazer uma coisa), conceitos (como algo funciona e porquê) e referência (definições, campos, limites, códigos de erro). Cada tipo tem o seu próprio modelo, para que as páginas se mantenham consistentes depois de entregarmos e a sua equipa acrescentar o quadragésimo artigo.

A lista de terminologia é o que mantém o conjunto coerente ao longo do tempo. Se a interface diz 'workspace', a documentação nunca diz 'project' ou 'account' para a mesma coisa. É um documento pequeno que evita a maior parte da confusão reportada pelos utilizadores.

• Artigos de tarefa: um objetivo, passos numerados, o resultado que o utilizador deve ver
• Artigos de conceito: o modelo por trás de uma funcionalidade, com um diagrama quando ajuda
• Páginas de referência: todos os campos, definições e limites, numa tabela fácil de consultar
• Resolução de problemas: a mensagem de erro tal como aparece, a sua causa e a correção