Documento

Um documento carrega o texto que o agente lê, e você o escreve com títulos, listas, ênfase, citação, código e link, tudo pelo teclado e sem sair do fluxo.

Logo abaixo do título há um campo que costuma ser ignorado e não deveria: a descrição. Ela não é lida junto com o conteúdo, e sim mostrada ao agente enquanto ele navega, quando ele ainda está decidindo se aquele documento é o que responde. Uma boa descrição economiza uma leitura inteira.

Não existe salvar

Toda alteração no texto e na organização vira cópia de trabalho por si só, sem botão, sem confirmação e sem trabalho perdido ao fechar a aba. Se uma alteração não conseguir ser gravada, você é avisado sem perder o que escreveu, e a gravação é retomada sozinha quando der.

O que o agente lê não muda enquanto você escreve, porque ele lê a versão publicada. Escrever é seguro por construção.

Escreva para quem lê por caminho

O agente raramente lê um documento inteiro, já que ele endereça um caminho, e um caminho pode apontar tanto para o documento todo quanto para uma seção dentro dele. Isso muda o que conta como um documento bem escrito.

• Um título de seção é um endereço, então escreva títulos que digam o fato em vez de anunciar o assunto, porque Prazo para devolução acha e Considerações não.
• Uma seção responde uma coisa, porque se ela responde três o agente lê três para usar uma.
• O fato vem antes do contexto, de modo que quem lê possa parar na primeira linha e já ter o que precisa.
• Nada de referência solta, já que "conforme descrito acima" não sobrevive a uma leitura por seção, em que o acima pode nunca ter sido lido.

Nenhuma dessas regras é sobre agradar a máquina. São as mesmas coisas que fazem um documento ser útil para uma pessoa apressada, que é o leitor que todo texto de referência realmente tem.

O que não colocar aqui

Processo. Uma sequência de etapas com decisões é um procedimento, onde ela é executada e conferida; aqui seria apenas um texto sobre ela.

Regra com condição que o sistema pode avaliar. "Acima de R$ 5.000 exige aprovação" rende muito mais como Condição do que como frase, porque escrita como etapa ela não depende de o agente ter lido o documento certo.

Instrução de comportamento. Como o agente fala é instrução do agente, não fato do negócio.

O que fica aqui é o que é verdade sobre o mundo: prazos, preços, políticas, definições, exceções, o que a empresa faz e o que ela não faz.