Regras de conteúdo para mecanismos de resposta

Um mecanismo de resposta nunca exibe sua página. Ele exibe um trecho dela ou uma frase reconstruída a partir de um trecho, e o leitor para aí. Portanto, a unidade que você está escrevendo é a seção, não o documento — e as regras abaixo são as que o Docsbook aplica às seções, cada uma com o mecanismo sobre o qual atua e a fonte que a estabelece.

Três coisas que esta página não é. Ela não é a camada de marcação — isso é Respostas estruturadas. Ela não é a lista do que aumenta as chances de citação depois que você já foi recuperado — isso é Sinais de citação, que trata dos tamanhos de efeito medidos e das coisas que não devem ser feitas. Esta página reúne as regras de escrita e, para cada uma delas, uma resposta honesta à única pergunta que importa quando um fornecedor declara uma regra: seu produto realmente faz isso ou está dizendo para eu fazer?

O que significam os três rótulos de aplicação#

As regras em resumo#

Regra 1 — Uma página responde a uma tarefa, na forma que essa tarefa exige#

Um tutorial, uma explicação, um guia prático, uma tabela de referência e uma FAQ são cinco formas diferentes, e misturá-las produz uma página que não responde completamente a nenhuma pergunta. Quando o Docsbook gera um site, ele as escreve como páginas separadas, com briefings separados: as páginas de explicação recebem títulos com sintagmas nominais e nenhum comando, as páginas de guia prático recebem um título no formato "Como alcançar um objetivo específico" e etapas numeradas orientadas a objetivos, sem teoria de base, e as páginas de referência recebem uma tabela por grupo.

O que isso faz com um agente de respostas. O mecanismo associa um tipo de pergunta a um tipo de passagem. Uma pergunta conceitual é mal recuperada em uma página cujas seções são etapas imperativas, e uma pergunta procedimental é mal recuperada em um texto que explica por quê. A forma de guia prático tem uma segunda consequência mecânica no Docsbook: um título que começa com "Como" seguido por uma lista numerada de três ou mais etapas é exatamente o que o detector HowTo lê; portanto, escrever a forma corretamente também produz a marcação — veja Respostas estruturadas.

Evidências. A autoavaliação de conteúdo útil do Google pergunta se "o título principal ou o título da página fornece um resumo descritivo e útil do conteúdo" e, separadamente, se ele "evita exageros ou uma natureza chocante" (Google, criando conteúdo útil). Um título de página que nomeia uma única tarefa satisfaz ambos por construção. A divisão em cinco formas é uma prática própria do Docsbook; nenhuma fonte pública a mensura.

Apenas recomendado. As formas estão nos briefings de página que o gerador segue. Nada verifica uma página escrita manualmente em relação a elas.

Regra 2 — Escreva o título como a pergunta que o leitor digitou#

Não "Limitação de taxa", mas "O que acontece quando atinjo o limite de taxa?". Use as palavras do leitor, não o nome interno do subsistema.

O que isso faz para um agente que responde. Isso coloca o texto da consulta dentro do documento. A recuperação calcula a similaridade entre uma pergunta e uma passagem, e a maneira mais barata de aumentar essa pontuação é fazer com que a passagem contenha a pergunta. Esse é o mesmo efeito explorado deliberadamente pela expansão de documentos: Nogueira et al. preveem "quais consultas serão feitas para um determinado documento" e as acrescentam a ele, relatando "o estado da arte em duas tarefas de recuperação", com a recuperação sozinha se aproximando da eficácia de reclassificadores neurais muito mais caros (arXiv 1904.08375). Um título em forma de pergunta é essa expansão, escrita pela pessoa que já sabe qual pergunta a seção responde. No Docsbook, ele também é uma entrada do detector — um título ### que termina com um ponto de interrogação se torna um Question na marcação FAQPage.

Indícios. arXiv 1904.08375, além do mecanismo acima. Observe o que nenhuma fonte sustenta: nada publicado afirma que um título em forma de pergunta fará com que você obtenha um snippet em destaque. Quando perguntado sobre como marcar uma página para isso, o Google responde: "Você não pode. Os sistemas do Google determinam se uma página seria um bom snippet em destaque para a solicitação de pesquisa de um usuário e, em caso afirmativo, a elevam" (Google, snippets em destaque).

Apenas recomendado. Os agentes de escrita formulam os títulos dessa maneira; nada reescreve um título que você escreveu.

Regra 3 — Cada seção deve ser legível sem nada acima dela#

Uma seção que começa com “Como mencionado acima, isso assume 30 segundos por padrão” torna-se inutilizável no momento em que é separada do parágrafo ao qual se refere — e será separada dele na primeira recuperação.

O que isso faz com um agente de respostas. Por padrão, o Docsbook indexa sua documentação na granularidade de títulos: uma unidade incorporada por seção, não por página. O texto incorporado de cada unidade recebe como prefixo a trilha completa de títulos da seção — Billing > Refunds > Limits — precisamente porque uma seção chamada “Limites” significa algo diferente sob Webhooks e sob chat de IA, e o vetor precisa carregar essa informação. As unidades têm um limite de 6.000 caracteres; uma seção mais longa que isso é truncada, portanto um fato oculto no final de uma seção muito longa não está presente no vetor. Na granularidade por linha, blocos de parágrafo com 20 caracteres ou menos são descartados como ruído.

Evidências. A granularidade da recuperação é uma variável mensurável, e unidades mais granulares e autossuficientes têm melhor desempenho. Chen et al. comparam unidades de documento, passagem e frase com “proposições” — “expressões atômicas dentro do texto, cada uma encapsulando um fato distinto e apresentada em um formato conciso e autossuficiente de linguagem natural” — e relatam que “indexar um corpus por unidades granulares, como proposições, supera significativamente unidades no nível de passagens em tarefas de recuperação” (Recuperação X densa, arXiv 2312.06648). A versão do lado do fornecedor sobre a mesma descoberta, e o modo de falha que ela produz em uma prosa que não explicita seu próprio assunto, está em Sinais de citação.

Aplicado automaticamente — na parte sob responsabilidade do Docsbook. O prefixo da trilha, o limite da unidade e o limite de caracteres são aplicados a todas as páginas, sem nenhuma configuração para alterá-los. A parte sob sua responsabilidade é a prosa: nada pode restaurar um assunto que você não nomeou.

Regra 4 — Os níveis de título são um contrato, não uma escolha de estilo#

Use H2 para uma seção, H3 para uma pergunta dentro dela e não pule um nível para obter uma fonte menor.

O que isso faz com um agente de respostas. Duas coisas. A árvore de títulos é o que divide sua página nas unidades da Regra 3, portanto, pular um nível coloca uma seção sob o elemento pai errado e atribui ao vetor dela o breadcrumb incorreto. E o detector de FAQ do Docsbook lê exatamente um formato: uma seção H2 cujos elementos filhos H3 são as perguntas, ou qualquer H3 que termine com um ponto de interrogação. Uma FAQ escrita com seções H3 e perguntas H4 não produz nenhuma marcação, silenciosamente — a falha de AEO mais comum que vemos.

Evidências. "Os títulos comunicam a organização do conteúdo na página. Navegadores da Web, plug-ins e tecnologias assistivas podem usá-los para fornecer navegação na página", e "Pular níveis de título pode ser confuso e deve ser evitado sempre que possível: certifique-se de que um <h2> não seja seguido diretamente por um <h4>" (W3C WAI, títulos).

Apenas recomendado, e esta é uma lacuna real: nada no Docsbook avisa que você pulou um nível ou que sua seção de FAQ não correspondeu a nada. Verifique com um validador — consulte Respostas estruturadas.

Regra 5 — O texto do título é dono da sua âncora; nunca escreva uma manualmente#

Links diretos, resultados de pesquisa e citações de IA apontam para page#anchor. Cada uma dessas âncoras é derivada do texto do título pela mesma biblioteca usada pelo renderizador, e nenhum outro código pode tentar adivinhar uma.

O que isso implica para um agente que responde. Uma citação cuja âncora não existe leva o leitor ao topo de uma página longa, depois de lhe ter prometido uma seção específica. Nada gera erro; o link simplesmente está errado. O Docsbook calcula as âncoras chamando github-slugger, que é o que rehype-slug usa quando a página é renderizada, portanto a âncora pré-computada e o id renderizado não podem divergir. Antes de isso ser centralizado, um gerador de slugs feito manualmente foi comparado ao corpus deste repositório: 1,386 de 21,827 títulos — 6,3% — produziram uma âncora que não era o id na página, e 263 resultaram apenas em traços. 314 das divergências ocorreram em títulos exclusivamente ASCII ("Casos extremos & erros" elimina um separador a mais); as restantes eram não latinas, onde todos os títulos de um site em russo resultaram na mesma âncora inativa.

Evidências. A medição acima é deste repositório, não de um estudo publicado; trate-a como um número nosso. Não há fonte externa para ela, e nenhuma é necessária — a regra é que uma string com um proprietário deve ser consultada, não recalculada.

Aplicado automaticamente. As âncoras são calculadas em um único lugar para cada consumidor.

Regra 6 — A resposta precisa estar nos bytes, antes que qualquer JavaScript seja executado#

Se o texto só aparece depois que um navegador executa um script, um assistente que busca a URL recebe apenas um esqueleto.

O que isso faz com um agente que responde. Absolutamente nada — e esse é o ponto. Essa falha é invisível para toda verificação que lê seu Markdown, porque não há nada de errado com o Markdown. O audit_geo do Docsbook busca páginas de amostra sem um mecanismo JavaScript e verifica se pelo menos 200 palavras de texto corrido do corpo permanecem após a remoção das tags; abaixo disso, a página é reportada como uma ocorrência crítica, partindo do princípio de que apenas rótulos de navegação, um banner de cookies e uma tag de título podem ultrapassar um limite inferior. Ele executa a mesma verificação usando agentes de usuário de assistentes identificados, portanto uma CDN que fornece uma página a um navegador e um desafio a um assistente aparece como uma ocorrência separada.

Evidências. As orientações do Google para AI Overviews e AI Mode são explícitas ao afirmar que a correção é conteúdo textual, não marcação: "Garantir que o conteúdo importante esteja disponível em formato textual", juntamente com "Garantir que o rastreamento seja permitido no robots.txt" — e, no mesmo documento, "Você não precisa criar novos arquivos legíveis por máquina, arquivos de texto de IA ou marcação para aparecer nesses recursos" (Google, recursos de IA). A Perplexity descreve Perplexity-User como visitando uma página quando um usuário faz uma pergunta, a fim de "ajudar a fornecer uma resposta precisa e incluir um link para a página em sua resposta" (Perplexity, bots) — uma busca sem navegador.

Verificado e reportado. As próprias páginas do Docsbook são renderizadas no servidor, portanto um site hospedado no Docsbook passa nessa verificação por construção; a verificação existe para os sites que ele audita.

Regra 7 — Cada número em uma afirmação identifica aquilo que o produziu#

Uma frase que contenha um número deve ser rastreável até a observação que o produziu — não até uma lembrança plausível dela.

O que isso faz com um agente que responde. Um número errado é o único erro que sobrevive à correção: um assistente o repete, e a repetição dura mais que a sua edição. O Docsbook impõe isso a tudo que suas ferramentas de agente produzem. Cada achado contém evidence_refs apontando para entradas de evidências nomeadas, e o validador do contrato examina o próprio texto do achado em busca de dígitos: qualquer número que não apareça na evidência citada é uma violação, e o payload é enviado de volta ao modelo para correção, em vez de ser retornado a você. As únicas exceções são os dígitos únicos de 0 a 9, além de 10 e 100 — ordinais e pequenas quantidades dentro de prosa comum. A pontuação é calculada por código simples sobre as evidências reunidas, não pelo modelo, porque um valor de 0 a 100 escrito por um modelo de linguagem não é comparável ao mesmo número escrito pelo mesmo modelo na próxima semana.

Evidência. As perguntas do Google sobre conteúdo útil questionam se “o conteúdo apresenta informações de uma forma que faz você querer confiar nele, como fontes claras e evidências da experiência envolvida” (Google, criando conteúdo útil). A versão mensurada — de que adicionar estatísticas e citar fontes aumenta quanto de uma resposta gerada é atribuído a você — está em Sinais de citação, que é responsável por esses tamanhos de efeito.

Aplicado automaticamente à saída do agente. Um número que você digita em uma página por conta própria não é verificado por nada.

Regra 8 — Preços, limites e versões são copiados, nunca inferidos#

Cada preço e cada limite declarado em uma página gerada é copiado literalmente do material de origem lido nessa execução. Um plano cujo preço não esteja na fonte é escrito como "Entre em contato com a equipe de vendas".

O que isso faz com um agente de respostas. O preço é o fato mais citado sobre um produto e aquele sobre o qual um leitor age. Um preço "típico" inferido é indistinguível de um preço real quando um assistente o repete. O gerador do Docsbook inclui a regra no briefing, e o pipeline anônimo vai além: se uma varredura não encontrar nenhum preço, a página de preços não é escrita, partindo do princípio de que uma página de preços com números inventados é pior do que nenhuma página de preços.

Evidências. A política de dados estruturados do Google exige que a marcação seja "uma representação verdadeira do conteúdo da página" e proíbe marcar conteúdo que não esteja visível para os leitores (Google, diretrizes de dados estruturados); as orientações do Google sobre recursos de IA pedem que "os dados estruturados correspondam ao texto visível na página" (Google, recursos de IA). Nenhuma das duas diz algo sobre preços inventados — essa parte é uma regra própria do Docsbook, e nós a declaramos como nossa.

Aplicado automaticamente à página de preços gerada, que é descartada em vez de receber valores estimados. Em outros lugares, é uma instrução no briefing.

Regra 9 — O título e a descrição são escritos, não extraídos do H1#

O title do frontmatter prevalece sobre o H1 do corpo, que prevalece sobre o nome do arquivo. O description do frontmatter prevalece sobre o primeiro parágrafo do corpo.

O que isso faz a um agente de respostas. O título e a descrição são as duas strings que uma máquina lê antes de qualquer outra coisa, e ambas têm um modo de falha invisível na página. Derivar o título do H1 significa que um autor que edita o frontmatter para controlar o resultado da pesquisa não altera nada, e permite que o nome da marca seja anexado duas vezes — consumindo um terço da linha de um resultado de pesquisa com repetição. Derivar a descrição do corpo significa que a marcação de widgets e os restos de uma lista de cartões vazam para o que é mostrado ao leitor. O Docsbook corrige a precedência em um único lugar e trunca no limite de uma palavra, cortando no fim de uma frase quando há um disponível: 160 caracteres para <meta name="description"> e 400 para Open Graph e o description JSON-LD, ambos preenchidos a partir da mesma string escrita pelo autor para que nunca possam discordar.

Evidências. "Os snippets são criados principalmente a partir do próprio conteúdo da página", e o Google recomenda "descrições exclusivas para cada página" (Google, snippet). Para títulos: escreva "texto descritivo e conciso", evite "texto repetido ou padronizado" e "identifique sua marca nos títulos de forma concisa" (Google, link do título).

Aplicado automaticamente para a precedência e o truncamento. Os comprimentos são o limite definido pelo próprio Docsbook, não um limite publicado — consulte Limites.

Regra 10 — Uma página para a qual nenhum link aponta é uma página que nada recupera#

Todas as páginas devem ser acessíveis a partir de pelo menos uma outra página, e todos os links nelas devem funcionar.

O que isso faz para um agente que responde. Os rastreadores encontram páginas seguindo links; uma página que só existe no mapa do site é uma página que oferece a um rastreador um motivo fraco para ser buscada e nenhum motivo para ser considerada importante. O Docsbook cria um grafo de links em todo o conjunto de documentos e contabiliza, por página, os links recebidos e os links não resolvidos. Uma página com links quebrados ou com zero links recebidos é sinalizada no cartão do grafo de documentos, com a correção oferecida como uma ação.

Evidência. A lista do Google sobre o que realmente ajuda uma página a aparecer nas Visões gerais de IA e no Modo IA inclui "Tornar seu conteúdo facilmente encontrável por meio de links internos no seu site" (Google, recursos de IA).

Verificado e relatado. Nada adiciona um link por você, a menos que você peça a um agente para fazê-lo.

Limites e questões em aberto#

• Metade da lista não impede que faça a coisa errada. As regras 1, 2 e 4 são instruções que os agentes de escrita seguem ao redigir; as regras 6 e 10 são reportadas posteriormente; a regra 8 é aplicada de forma rigorosa apenas na página de preços gerada. Se escrever uma página manualmente — ou editar uma página escrita por um agente — nada no Docsbook a verifica em relação a esta lista. Ainda não existe um linter que reporte níveis de títulos ignorados e secções de FAQ que não correspondam a nenhum detetor, e a regra 4 é a que falha com mais frequência e de forma mais silenciosa.
• Os limites de caracteres da regra 9 são nossos, não da Google. A Google não publica qualquer limite de caracteres: "não há limite para o comprimento de um elemento <title>", e o link do título "é truncado nos resultados da Pesquisa Google conforme necessário, normalmente para se ajustar à largura do dispositivo" (Google, link do título). O mesmo se aplica às descrições. 160 e 400 são os limites usados por esta base de código, e o objetivo de 50–60 caracteres para o título e de 130–160 caracteres para a descrição nos briefings do gerador são regras de estilo internas. Trate-os como valores predefinidos razoáveis, não como limiares em relação aos quais alguma ferramenta o avalia.
• Em aberto: o limiar para páginas pouco extensas. O código do Docsbook calcula uma avaliação por página que considera uma página "pouco extensa" abaixo de 120 palavras, juntamente com "quebrada" e "órfã". As avaliações de links quebrados e páginas órfãs são apresentadas; a avaliação de página pouco extensa é calculada, exportada e testada por testes unitários, mas atualmente não é apresentada em nenhum painel, pelo que, na prática, não será informado de que uma página é pouco extensa. Os mínimos de palavras nos briefings do gerador — 300 a 400 palavras, dependendo do tipo de página — são regras de estilo internas sem uma fonte publicada que sustente esses números específicos. O que é fundamentado por fontes é apenas a orientação: a Google pergunta se o conteúdo "fornece valor substancial quando comparado com outras páginas nos resultados da pesquisa" (Google, criação de conteúdo útil).
• Em aberto: se os títulos em forma de pergunta aumentam a taxa de citações. O mecanismo de recuperação da regra 2 é real e fundamentado por fontes. O que nenhuma fonte pública estabelece é um aumento da taxa de citações especificamente decorrente da forma do título, em qualquer mecanismo de resposta. A expansão de documentos é medida em benchmarks de recuperação, não no ChatGPT ou nas Visões gerais de IA. Considere a regra 2 bem fundamentada no que diz respeito à recuperação e não comprovada no que diz respeito às citações, até que alguém publique a segunda medição.
• As regras 3 e 6 descrevem dois pipelines diferentes, e passar num deles não diz nada sobre o outro. A regra 3 é o índice semântico próprio do Docsbook sobre o seu Markdown; a regra 6 é o que um assistente externo obtém quando vai buscar o seu URL. Uma página pode estar perfeitamente dividida em segmentos para a pesquisa no seu site e ser invisível para o ChatGPT, ou o contrário. Não partilham qualquer código.
• Nada disto é medido em função dos resultados obtidos por si. O Docsbook pode informar que uma página está órfã, que uma secção não correspondeu ao formato de nenhum detetor ou que uma obtenção não devolveu prosa. Não pode informar que seguir estas regras fez com que fosse citado, e não afirma fazê-lo — consulte Sinais de citação para saber por que motivo uma execução não prova nada, e Como o Docsbook comprova as suas afirmações para conhecer o padrão a que estas páginas são submetidas.

Relacionados#

• AEO — o que um mecanismo de respostas precisa de uma página e o que a marcação ainda pode proporcionar
• Respostas estruturadas — os detectores alimentados por estas regras e como é uma falha
• Sinais de citação — os efeitos medidos e o que não fazer
• GEO — o bloco TL;DR, a data visível e a linha do autor
• SEO — indexação, URLs canônicos e rastreabilidade, a etapa anterior a tudo isto
• Pesquisa — a recuperação no site alimentada pela regra de divisão em blocos
• Widgets de conteúdo — as regiões de etapas e acordeão que os detectores entendem
• Como o Docsbook comprova o que afirma — a regra de evidência seguida por estas páginas