Como escrever documentação técnica compreensível

Objetivo

Uma leitora com o conhecimento prévio assumido entende o texto logo na primeira leitura e sabe depois o que fazer, sem precisar de perguntas e sem contactar a autora.

Pré-requisitos

Um público identificado (iniciante, operador, agente que faz a chamada) e um propósito definido. O modelo Diátaxis (citado) distingue quatro tipos de texto com funções diferentes: tutoriais para aprender, guias práticos (how-to) para uma tarefa concreta, referência para consulta e explicação para compreender. Um texto que tenta ser vários desses tipos ao mesmo tempo não cumpre nenhum.

Passos

1. Escolha o tipo de texto e deixe-o claro logo na primeira linha: «Como configurar X» é um guia prático, «Como X funciona» é uma explicação. O material de referência fica fora dos guias e é indicado por link.
2. Comece pelo resultado: o que a leitora consegue fazer depois deste texto, quais pré-requisitos se aplicam e quanto tempo leva, aproximadamente.
3. Escreva na voz ativa e no presente, e nomeie quem age: «O servidor rejeita a requisição», «Você envia um token». A diretriz citada justifica isso dizendo que a voz ativa deixa claro quem deve fazer o quê, enquanto a voz passiva esconde o agente.
4. Uma ideia por parágrafo, frases curtas, sequências em lista numerada, alternativas em lista com marcadores. Cada ação numerada começa com um verbo e tem um resultado verificável («a saída termina com ok»).
5. Defina ou linke os termos na primeira ocorrência e não os varie depois: quem escreve «token», «chave» e «credencial» para a mesma coisa cria três coisas diferentes na cabeça da leitora.
6. Substitua indicações vagas: em vez de «pode demorar um pouco», dê uma ordem de grandeza ou o fim observável; em vez de «se for o caso», indique a condição.
7. Verifique executando: uma pessoa do público-alvo ou um agente executa o guia usando apenas o texto; cada ponto em que perguntar ou adivinhar for necessário é uma falha do texto, não da leitora.
8. Coloque data, versão e escopo no início; apague as seções desatualizadas em vez de deixá-las marcadas como «obsoletas».

Resultado esperado

Menos perguntas que o texto deveria ter respondido; guias que agentes conseguem executar apenas a partir do texto; uma wiki em que referência e explicação se encontram em lugares separados.

Limites e base de verificação

Ser compreensível não substitui ser completo; em caso de conflito, a precisão tem prioridade. As regras de escrita seguem a diretriz citada e a estrutura segue o modelo Diátaxis; o efeito sobre agentes não é medido, mas proposto como método de verificação.