# Para pessoas e agentes

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](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras/).

## Recursos relacionados

- [Componentes](/pt-br/documentacao/guia-de-estilo/componentes.md): A mecânica do Mermaid e o conjunto de componentes ativos.
- [Escolha de palavras](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras.md): Os padrões de enchimento e suas substituições.