Para pessoas e agentes
Escreva uma vez para dois leitores: as escolhas de design que mantêm as páginas úteis para pessoas e para sistemas de retrieval.
Uma página de documentação tem dois leitores: uma pessoa na página, e uma máquina que recupera um pedaço dela para responder uma pergunta. A documentação é escrita uma vez, para os dois.
Seções que ficam de pé sozinhas
Um sistema de retrieval não retorna uma página. Ele retorna um chunk, em geral uma seção, sem o contexto ao redor. Então toda seção ## é escrita para ser lida sozinha. O título nomeia o conteúdo com especificidade suficiente para corresponder a uma busca, e a primeira frase funciona sem a seção anterior.
Diagramas como texto
Um diagrama é um fence de código Mermaid, nunca uma imagem. O texto do diagrama chega a um agente que lê a página como markdown; uma referência de imagem, não. Um diagrama também nunca fica sozinho: a prosa abaixo dele percorre o mesmo fluxo.
Uma régua para todo rascunho
As proibições de vocabulário e de padrões valem para qualquer autor. Uma página escrita por uma pessoa e uma rascunhada com um agente passam pela mesma régua: sem molduras repetidas, sem enchimento, sem travessões decorativos. Os padrões estão listados em Escolha de palavras.