Many docs sites end each page with "Was this page helpful?" and a thumbs up or down. It is a reasonable start, but "helpful" is vague. A page can be well written and still not answer what the reader came for.
Changing the wording gives you answers you can act on. Here is the question, why it works, and how to set it up.
The short answer
Ask "Did this page answer your question?" with Yes and No. Readers come to a docs page with a question, so this asks about the one thing that matters to them, and every No points to a page that needs work. Add an optional "What were you trying to do?" so a No comes with a reason.
Why "Did this page answer your question?" works
People open a docs page with a task in mind: set something up, fix an error, find a setting. The question asks whether that task got done, and readers can answer it honestly in one tap.
It also gives you a clear signal. A No means the reader left without what they needed. Because every page asks the same thing, you can rank your pages by No answers and know where to start.
How it compares with other common questions
| Question | What a low answer tells you | Drawback |
|---|---|---|
| Was this page helpful? | The reader was unhappy in some way | Too vague: helpful in what way? |
| Thumbs up / thumbs down | The same, without words | Readers aren't sure what they are rating |
| How would you rate this page? (1 to 5) | The page scored low | A 3 is hard to act on |
| Did this page answer your question? | The reader didn't get what they came for | It doesn't say why, so add a follow-up |
Word the answers clearly
- Use the words Yes and No on the buttons. Icons on their own leave readers guessing.
- Make the question itself the heading, so readers see what they are answering.
- Skip a "Not sure" option. It gives undecided readers an easy way out, and those answers tell you nothing.
- Use the same wording on every page, or the pages can no longer be compared.
Place it where readers finish
Put the question at the end of the page content, before the footer and the "next page" links. On long reference pages, readers often jump to one section and leave, so a side tab that stays on screen reaches them too. Avoid pop-ups: they interrupt readers in the middle of a task.
Ask one follow-up after the No answers
A No tells you which page failed. The follow-up tells you how. "What were you trying to do?" works well as optional free text, because readers describe the task in their own words, and those words often name the missing step.
If your survey tool shows every question to every reader, word the follow-up so it also makes sense after a Yes, and let readers skip it.
Example
Example: an API documentation site
Say you look after 150 pages of API documentation, and you replace the thumbs with "Did this page answer your question?" and an optional "What were you trying to do?".
The authentication page had been collecting thumbs-down votes for months, and nobody knew why. Now its No answers come with comments such as "trying to refresh an expired token". The page explains how to get a token but never how to refresh one. You add that section, and the new answers show whether it closed the gap.
What to do with the answers
Once a week, open the pages with the most No answers, read their comments and fix the step readers name. Then compare the same number of weeks before and after the change. Our guide "Find the pages that leave readers stuck" walks through that process in full.
Where Asklet fits
Asklet shows the question on every docs page with one snippet in your docs layout, and a pattern such as /docs/** covers every page, including new ones. You can set the widget heading per page, results come back per page with the comments next to them, and the widget sets no cookies.
It works with docs tools that accept a plain iframe in the page layout, such as Docusaurus, MkDocs, VitePress and Mintlify.
Your next steps
-
Replace your current question with "Did this page answer your question?"
Use the same wording on every docs page.
-
Label the buttons Yes and No
Words, not icons alone, and no "Not sure".
-
Put it at the end of the page content
Add a side tab on long reference pages.
-
Add an optional "What were you trying to do?"
Free text, so readers can name the task in their own words.
-
After two weeks, open the pages with the most No answers
Read their comments and fix the step readers name.
Try these steps on your own site. Asklet adds the questions to every page with one snippet. Free plan, no card needed. Compare the plans.
Start freeCommon questions
Is "Was this page helpful?" a bad question for documentation?
It is not bad, but it is vague. "Did this page answer your question?" asks about the reader's task, so a No tells you clearly that the page missed what the reader needed.
Should I use thumbs up and thumbs down icons?
Use the words Yes and No, with or without icons. Icons alone leave readers unsure whether they are rating the page, the product or the writing.
Should every documentation page ask the question?
Yes. When every page asks the same question, you can compare them and see which ones fail most often. The pages that need work are often not the ones you expected.
What should I ask after a reader answers No?
Ask "What were you trying to do?" as optional free text. Readers describe their task, and the description usually points to the missing step or section.
Related
More from the blog
- Privacy and law EU cookie consent changes: where the Digital Omnibus stands in October 2026 9 min read
- Privacy and law Session replay and pixel lawsuits: what website owners should know 9 min read
- Privacy and law How to make a feedback widget accessible, and what the European Accessibility Act asks 9 min read