Skip to main content
Asklet
Sign in Start free
All posts

Docs and guides

Find the pages that leave readers stuck

By 6 min read

Readers who get stuck rarely tell you. They leave, search again, open a support ticket or give up. By the time a ticket arrives, the page that failed them is several clicks back and nobody knows which one it was.

This guide is for anyone who looks after help articles, documentation or how-to guides. It shows how to find the pages that let readers down, decide which to fix first, and check that the fix worked.

The short answer

Ask "Did this page answer your question?" on every page, followed by "What went wrong?". The pages with the most No answers are where readers get stuck. Read their comments, fix the step that readers name, and compare the answers before and after the change.

How to spot an unclear documentation page

You may already be seeing some of these:

  • Support keeps getting the same question, even though an article covers it.
  • Readers search your help centre for the same topic right after reading the page about it.
  • A page has numbered steps, and readers leave halfway through.
  • Comments say "doesn't work", "where is..." or "I don't see this button".
  • The product changed last month and the page didn't.

Why tickets and search logs don't point to the page

Support tickets tell you the topic, in the reader's words, after the fact. Search logs tell you what readers typed. Analytics tells you where they left. None of them says which page, or which step on it, let the reader down.

To find that, you need an answer from readers while they are still on the page.

Ask the question that finds them

Use the same short survey on every help page, so the pages can be compared with each other:

  1. "Did this page answer your question?"

    Yes / No. It takes one tap, and the share of No answers gives you a ranking of your pages.

  2. "What went wrong?"

    Multiple choice with options such as "The steps don't match what I see", "A step is missing", "Too technical", "My case isn't covered" and "Something else". Every reader sees this question, so let readers skip it after a Yes.

  3. "What were you trying to do?"

    Optional free text. These answers often name the exact step or screen.

Tip: Ask on every page, not only the ones you suspect. The pages that leave readers stuck are often not the ones you expected.

Example

Example: a help centre for a booking app

Say you look after 80 help articles for a booking app. You add the three questions to every article with one path pattern.

Two weeks later, "How to change a booking" has more No answers than any other page, and most of them picked "The steps don't match what I see". One comment says "there is no Edit button". The last release moved Edit into a menu, and the article still shows the old screen.

The fix takes a few minutes: a new screenshot and the new button name. Over the next weeks, the share of Yes answers on that page shows whether it worked.

Decide which pages to fix first

Rank by the number of No answers, not the percentage. A page with 40 No answers out of 200 lets down more readers than one with 4 out of 10. Then move up anything about a task readers must complete, such as signing in, paying or setting up.

  • First: busy pages about important tasks with many No answers
  • Next: busy pages with many No answers about anything else
  • Then: quiet pages with a high share of No answers once they reach 10 answers
  • Last: everything else, at your regular review

Fix the page, then check that it worked

When you rewrite a page that leaves readers stuck:

  • Match the screens exactly: the same button names, menu names and order.
  • Give each step one action, and say what the reader should see after it.
  • Answer the most common comment near the top of the page.
  • Cover the case readers say is missing, or link to the page that does.
  • End with a link to the task readers usually do next.

Then compare the share of Yes answers over the same number of weeks before and after the change. If it hasn't moved, read the newest comments: the next problem is usually a different step.

Make it a weekly habit

Set aside 15 minutes a week: read the new comments and look at the pages with the most new No answers. After each product release, check the pages that show the screens that changed. Grouping pages by product area lets you see whether one area keeps letting readers down.

Where Asklet fits

Asklet adds the survey to every page with one snippet in your docs template, and a pattern such as /docs/** covers all of them, including pages you add later. Each page can have its own heading, such as "Did this page help?". Results show per page, with the comments next to the numbers, and themes group pages by product area.

It works with docs tools that let you add a plain iframe to the page layout, such as Docusaurus, MkDocs, VitePress and Mintlify. Answers are anonymous, so you can't reply to a reader. Put a link to support on the page for readers who need help right away.

Your next steps

  1. Add "Did this page answer your question?" to every help page

    Use one pattern, such as /docs/**, so new pages are covered too.

  2. Add "What went wrong?" with four or five options

    Include "Something else", and end with an optional free-text question.

  3. After two weeks, list the five pages with the most No answers

    Move up any page about signing in, paying or setting up.

  4. Read their comments and fix the step readers name

    Match the screens exactly and give each step one action.

  5. Compare before and after

    Use the same number of weeks on each side of the change.

  6. Repeat every week and after every release

    Read the new comments and look at the pages with the most new No answers.

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 free

Common questions

What is a good share of Yes answers for a help article?

There is no number that fits every help centre. Compare your pages with each other, and each page with itself over time. The pages at the bottom of your list and the ones that are getting worse are the ones to work on.

Should I ask on every page or only the important ones?

On every page. One snippet and one path pattern cover them all, and the pages that leave readers stuck are often not the ones you would have picked.

Can I reply to a reader who left a comment?

No. Answers in Asklet are anonymous, so there is no one to reply to. Add a link to support on your pages for readers who need help with their own case.

How is this different from a support form?

A support form hears from the few readers who decide to write in, about their own problem. A question on every page hears from many more readers, tells you which page failed them, and needs no reply.

Related

More from the blog

Get your first answers today.

Set-up takes a few minutes, and the free plan covers one website or app.

Start free

Free plan, no card needed.

en