Skip to main content
Documentation structure is a hypothesis. You believe readers will recognize a label, choose a section, and find the page that helps. Seeing what users do on your site tells you whether that hypothesis is right. No single metric captures documentation quality so you must combine several signals and look for patterns.

​
Start with questions, not page views

High traffic can mean a page is valuable, confusing, or simply linked from the product. Low traffic can mean a page is unnecessary—or impossible to find. Begin with questions such as:
  • Can new users find the quickstart?
  • Do people search for a term your navigation doesn’t use?
  • Which tasks still generate support tickets after you document them?
  • Where do readers leave a multi-page procedure?
Choose signals that help answer a question rather than collecting numbers without a decision in mind.

​
Review search behavior

Search terms show readers’ language and intent. Look for:
  • Frequent queries with no useful result
  • Queries that use a different term from your docs
  • Repeated searches that become more specific
  • Searches for content that exists but ranks poorly
If readers search for “team permissions” while your docs say “workspace roles,” adding the reader’s language to titles, descriptions, or introductory text may improve discovery without changing the canonical product term.

​
Connect support questions to content

Tag support tickets by task or topic. When the same question repeats, ask:
  1. Is the answer missing?
  2. Does it exist under a label readers won’t recognize?
  3. Is it on the right page but buried in the wrong section?
  4. Is the documentation accurate but the product workflow still confusing?
Documentation cannot fix every product problem. Treat repeated confusion as evidence, not automatically as a request for more prose.

​
Test real tasks

Give a colleague who doesn’t know the structure a realistic task. Ask them to think aloud while they find the answer using only the site. Watch where they look first, which labels they misunderstand, and when they backtrack. Don’t guide them. A five-minute task test often reveals more than a discussion among people who already know where everything lives. Test the highest-value tasks first:
  • Reach a first successful result
  • Configure authentication
  • Recover from a common error
  • Find a specific reference value

​
Use assistant conversations carefully

Questions sent to an AI assistant are another source of user intent. Review questions the assistant can’t answer, answers with weak citations, and topics users ask repeatedly. An assistant can sometimes compensate for poor navigation, so don’t treat a correct answer as proof that the underlying page is easy for humans to find.

​
Turn evidence into a small change

For each pattern, choose the smallest change likely to help:
  • Rename a heading or navigation group
  • Improve a page title or description
  • Add a missing cross-link
  • Split a mixed-topic page
  • Create a new page for a recurring task
  • Remove outdated content that competes with the right answer
Define what you expect to improve, make the change, and check the same signal again. Documentation gets better through small, testable iterations. Next up: Keep docs accurate as your product grows — Build the maintenance rhythm that keeps improvements from drifting out of date.