Como escrever documentos bons

Um documento de conhecimento útil funciona para dois leitores: uma pessoa que está aprendendo o assunto e um sistema de busca que seleciona evidências para uma pergunta. Você não precisa escrever em uma linguagem de máquina especial. Você precisa tornar os fatos fáceis de identificar e difíceis de interpretar erroneamente, mesmo quando uma seção é lida separadamente do restante.

Pense em um cartão de receita. “Cozinhe como de costume até ficar pronto” supõe experiência e contexto ausente. “Asse o prato de legumes coberto até que o centro esteja quente” fornece uma ação mais clara, embora uma receita aprovada também precise de sua temperatura e tempo específicos. A escrita de conhecimento tem o mesmo desafio: substituir suposições pelas informações que alguém precisa para agir corretamente, sem inventar detalhes apenas para soar preciso.

Dê a cada documento um objetivo claro #

Use um tópico por documento, onde um tópico é uma pergunta ou procedimento coerente, e não um tamanho de página arbitrário. “Devolução de bicicleta montada” é mais fácil de encontrar e manter do que “Várias informações de clientes”. Um procedimento pode conter várias etapas e ainda ser um único tópico. Dividir cada frase em um documento separado destruiria as relações que tornam o procedimento compreensível.

Escolha um título descritivo que inclua o assunto e o objetivo do leitor. “Reivindicações de despesas: envio de recibos de viagem” é mais útil do que “Atualização de despesas”. Um título deve distinguir o documento do material vizinho sem depender do nome da pasta. Os resultados de busca podem exibir apenas o título, e uma seção recuperada pode não chegar com toda a hierarquia de pastas.

Abra com uma breve declaração de escopo: quem a regra se aplica, o que cobre e quaisquer exclusões importantes. Mantenha anúncios não relacionados, histórico e material de marketing em outro lugar. Eles podem ser documentos úteis por si só, mas dificultam a localização de uma resposta procedural quando misturados na mesma fonte.

Torne as seções autossuficientes #

Uma seção autossuficiente inclui informação suficiente para entender sua afirmação principal sem ler um trecho não relacionado primeiro. Isso importa porque a recuperação costuma selecionar fragmentos, partes menores dos documentos, em vez da fonte completa. Um fragmento pode ser excelente em corresponder à pergunta, mas ainda ser inutilizável se o assunto ou exceção foi deixado para trás.

Pronomes como “ele”, “eles” e “isto” não são inerentemente errados. Eles se tornam arriscados quando seu significado depende de texto fora da seção selecionada. Repita o substantivo importante quando um novo título ou parágrafo começar. Repetição natural e moderada é melhor que uma frase elegante cujo sujeito desaparece durante a recuperação.

Os trechos fictícios a seguir ilustram a qualidade da escrita, não uma política real de empresa.

O trecho melhorado nomeia o produto, distingue duas situações e identifica o próximo passo. Deliberadamente não inventa uma duração de devolução: se a fonte aprovada não contém esse fato, o escritor deve obtê‑lo. Boa escrita expõe informações ausentes em invés de escondê‑las atrás de prosa confiante.

Uma seção que se refere a outra política deve explicar por que essa referência importa. “Para danos na entrega, siga o procedimento de reivindicação de danos ao invés do procedimento padrão de devolução” é útil. “Veja o outro documento” não é. Onde o destino real existe, inclua um link descritivo para que a pessoa possa verificar a regra completa.

Substitua qualificadores vagos por fatos aprovados #

Palavras como “em breve”, “normalmente”, “grande” e “recente” podem ocultar decisões importantes. Pergunte qual evento inicia o prazo, qual unidade uma quantidade usa e quais condições mudam a regra. Se a fonte fornece uma data, esclareça se é a data de publicação, data de vigência ou data de expiração. São fatos diferentes.

O prazo ilustrativo e a data tornam a estrutura visível; não são recomendações para uma política real de despesas. Observe que o limite de aprovação ainda precisa de uma referência confiável ou de um valor aprovado. Nunca preencha valores ou datas ausentes por intuição. A precisão ajuda apenas quando os fatos estão corretos.

Separe uma promessa de uma estimativa. “A equipe pretende revisar solicitações dentro da janela de serviço declarada” não equivale a garantir aprovação dentro de um prazo. Preserve a incerteza quando a fonte realmente a contém, e explique as condições por trás dessa incerteza. Remover todas as qualificações pode tornar um documento mais curto, mas seu significado menos preciso.

Use perguntas e tabelas quando ajudarem #

Um formato de perguntas e respostas, ou Q&A, emparelha uma pergunta realista com uma resposta direta. Funciona bem para preocupações recorrentes, como “Um colega pode enviar uma reivindicação de despesa por mim?”. Comece com a resposta, depois explique as condições e o próximo passo. Evite criar muitas páginas quase idênticas para diferentes formulações; essas cópias são mais difíceis de manter e podem sobrecarregar os resultados de busca.

Tabelas são úteis quando os leitores devem comparar os mesmos atributos entre opções. Dê a cada coluna um cabeçalho claro, repita o nome da opção em cada linha e evite células mescladas que perdem seu significado ao serem convertidas em texto simples. A tabela abaixo é uma estrutura ilustrativa, não uma oferta de serviço.

Após a conversão, verifique se cada linha ainda conecta o tipo de solicitação aos seus requisitos. Uma tabela que parece atraente em PDF pode se tornar uma sequência confusa de valores em texto extraído. A escrita e o formato do documento devem funcionar juntos.

Revise o documento como evidência #

Mantenha a revisão prática. Peça a um colega que não conhece o assunto para interpretar um trecho e explicar o que ele faria. Se a resposta dele diferir da intenção do responsável, melhore a fonte antes de culpar a recuperação. Repita a verificação após edições importantes, pois um parágrafo encurtado pode separar acidentalmente uma regra de sua exceção.

Relacionado: no AIVAX, essas passagens se tornam documentos em uma coleção. Uma estrutura clara facilita a recuperação e avaliação desses documentos, mas a qualidade da escrita por si só não prova que um agente os usará fielmente.

Próximo passo: verifique as respostas resultantes em Measuring adherence and hallucination.