Feedback da página

O feedback da página no Docsbook é um controle de Esta página foi útil? que o leitor responde com um clique — sem formulário, endereço de e-mail ou conta. O voto é registrado como um evento associado à página e como um webhook sobre o qual você pode agir. Coletá-lo não chama nenhum modelo e não custa nada.

A avaliação é um indicador, não uma pontuação. Esta página trata tanto do que um voto negativo não comprova quanto de como coletar um.

O que você obtém#

• Uma avaliação com um clique em todas as páginas, em um ou dois lugares, em todos os planos.
• Um voto que chega imediatamente aos seus próprios sistemas — um webhook feedback.received e um segundo webhook chat.negative_feedback quando a avaliação é negativa, para que uma avaliação ruim chegue ao canal da sua equipe no momento em que acontece.
• Um histórico por leitor. Na linha do tempo do visitante, o voto aparece como "Avaliou a página como útil" ou "Avaliou a página como não útil", ao lado de tudo o que o leitor fez, que é onde um único voto se torna interpretável.
• Uma fila que já sabe o que fazer com isso. Duas rotas de agente já disponíveis começam com feedback negativo e com perguntas de chat sem resposta e terminam em uma página em rascunho.

O que um leitor pode avaliar?#

Existem três controles, e eles não medem a mesma coisa.

A barra abaixo da página é a que a maioria dos projetos deseja ativar. O leitor chega até ela ao terminar a página, que é o momento em que já tem uma opinião; o controle do esquema só é visto por um leitor cujos olhos já estão na barra lateral direita. Os dois controles da página registram dados em uma única série — são dois lugares para fazer a pergunta, não duas métricas.

Os polegares das respostas de IA formam uma série genuinamente diferente e carregam campos diferentes: o ID da conversa e a pergunta que recebeu o voto, porque uma avaliação contendo apenas um caminho é um contador sobre o qual ninguém pode agir. A opção Relatar problema no menu de opções da resposta registra o mesmo evento de não gostei.

Um voto por controle, por visualização da página. Após votar, os botões são bloqueados e um breve agradecimento substitui a pergunta. A proteção é específica de cada controle, portanto um projeto com ambos os controles da página ativados pode receber dois votos do mesmo leitor na mesma página — isso é aceito deliberadamente: um leitor que vota duas vezes de propósito está dizendo a mesma coisa duas vezes, e eliminar duplicatas entre superfícies exigiria um estado compartilhado sem nenhum ganho de sinal.

Ativar o feedback da página#

Abaixo da página (ativado por padrão):

1. Abra o site da documentação enquanto estiver conectado.
2. Abra Float Widget → Configurações → aba Conteúdo.
3. Ative Avaliar esta página.

No painel "Nesta página":

1. Abra Float Widget → Configurações → aba Barra lateral direita.
2. Ative Avaliar página.

Ambas as opções também podem ser definidas a partir de um cliente MCP com update_ui_settings (show_content_feedback, show_page_feedback).

O que é armazenado por voto#

Um voto em uma página é deliberadamente minimalista. Não há campo de texto livre em nenhum dos controles da página, nem ID de sessão ou qualquer coisa digitada pelo leitor:

Há dois comportamentos que vale a pena conhecer, pois eles alteram o significado dos seus números:

• Votos da sua própria equipe são excluídos das análises, mas ainda são enviados aos seus webhooks. O tráfego interno é ignorado na gravação da análise, pois testar sua própria página não é um sinal do leitor — mas o proprietário ainda deve ser informado de que uma avaliação ocorreu.
• O campo comment existe no payload e nunca é preenchido por estes controles. Ele existe para uma superfície que coleta esse campo; atualmente, nenhum dos controles da página o faz.

Um voto de resposta de IA armazena o projeto, a página em que o leitor estava, o ID da conversa e a pergunta — nenhum texto da resposta e nenhuma identidade do leitor além do mesmo hash de IP.

O que o proprietário vê#

O registro de um webhook está disponível em todos os planos; tanto o caminho MCP quanto o caminho REST verificam a mesma capacidade, e apenas três eventos avançados (pico de tráfego, queda de tráfego, ferramenta MCP chamada) são separados. Várias descrições de ferramentas MCP ainda anunciam esses dois eventos como Pro — esse texto está desatualizado, não o comportamento.

Uma questão — leia a aba Feedback como a série de respostas da IA, não como a série de páginas. Os totais e as linhas por página da aba são criados a partir de uma consulta sobre docs.ai_like / docs.ai_dislike, os eventos gravados pelos votos de resposta da IA. Os controles da página gravam docs.page_feedback_up / _down, e nenhuma consulta por trás dessa aba os lê. Portanto, um voto em uma página hoje chega aos seus webhooks e à linha do tempo do visitante, mas não chega às contagens da aba Feedback. get_negative_feedback tem a mesma estrutura: seu próprio comentário no código afirma que o evento no nível da página "não é incluído aqui". Até que isso seja corrigido, trate a aba Feedback como uma medida das respostas do assistente e use o feed de eventos ou um webhook para os votos nas páginas.

De uma avaliação negativa à próxima página que você escrever#

Uma avaliação não é a conclusão. O que a torna acionável é o que vem junto dela: as pesquisas que não retornaram nada, as perguntas que o assistente não conseguiu responder e o que o leitor fez depois de votar.

Duas rotas de agente já vêm com essa sequência configurada, ambas no Pro:

Melhorar a documentação com base no feedback dos usuários — recomenda-se executar semanalmente. Ela lê as páginas que os leitores marcaram como ruins e, antes de repetir uma correção, lê o que as correções anteriores dessas páginas já fizeram; depois pergunta qual tarefa o leitor estava tentando concluir e só então edita. A etapa de histórico de alterações existe porque a versão sem ela media a saúde de uma página segundos depois de reescrevê-la, um número que ainda não poderia ter mudado.

Preencher lacunas com base nas conversas com o assistente — recomenda-se executar no evento chat.no_answer. Ela lê as perguntas que o assistente não conseguiu responder, separa uma lacuna na documentação de uma pergunta inadequada, escolhe aquela que vale a pena escrever hoje e cria um rascunho dessa página.

Os prompts por trás de cada botão Melhorar no painel seguem as mesmas quatro regras, que também devem ser aplicadas manualmente: avalie cada número em relação a algo e diga com o que você o comparou; cite as páginas e os eventos que você realmente leu; uma métrica que você não consegue ler está ausente, não é zero; e pare no diagnóstico antes de editar qualquer coisa.

Coletar uma avaliação não chama nenhum modelo nem é contabilizado. As rotas de agente acima envolvem trabalho de modelo e consomem o saldo do seu projeto — consulte a página de preços.

Por que esta é a maneira certa (evidências)#

A leitura prática dessas quatro linhas: vale a pena abrir uma página com dez avaliações negativas; uma página com três avaliações positivas não é evidência de que funciona; e uma página sem votos é uma página sobre a qual você não sabe nada, não uma página de que ninguém não gostou.

Limites#

• A aba Feedback atualmente não contabiliza votos nas páginas. Consulte o bloco abaixo da pergunta. Esta é a única afirmação nesta página que uma versão anterior desta documentação apresentou incorretamente, e ela é declarada aqui em vez de ser simplesmente omitida.
• Um voto não contém um motivo. Nenhum dos controles da página coleta texto livre, portanto um voto negativo informa que algo estava errado, mas nunca o que. A avaliação negativa da resposta da IA é mais rica apenas porque inclui a pergunta.
• As avaliações são por visualização, não por leitor. Um leitor que retornar amanhã poderá votar novamente, e um projeto com os dois controles de página ativados poderá receber dois votos de um leitor em uma única visualização da página.
• O feedback é mais informativo em páginas instrucionais — tutoriais e guias práticos, nos quais o leitor concluiu ou não a tarefa. Em uma tabela de parâmetros, uma avaliação informa muito pouco.
• Não publicamos nenhum benchmark de qual seria uma taxa de feedback típica do Docsbook. Nenhuma distribuição entre clientes foi medida, portanto não há um número “saudável” com o qual você possa se comparar. As fontes externas acima tratam de feedback voluntário em geral, não de sites do Docsbook.
• Há um campo de comentário no payload, mas nada o preenche. Se você criar uma interface que colete um comentário, o contrato do webhook já tem um lugar para ele; pronto para uso, ele é sempre null.

Relacionado#

• Chat de IA — o assistente cujas respostas têm seus próprios votos positivos separados.
• Qualidade das respostas — o que acontece com uma pergunta que o assistente não conseguiu responder.
• Pesquisa de texto completo — pesquisas malsucedidas são o outro sinal de que uma página está ausente ou tem um nome incorreto.
• Análise da web — verifique o tráfego de uma página antes de reescrevê-la com base em três votos.
• Webhooks — feedback.received e chat.negative_feedback completos, assinados e reenviados.