Improving docs

Docs improve the way software improves: someone notices a problem, someone diagnoses the cause, someone writes the fix, the fix ships. The difference is that docs teams usually don't have a bug tracker for content, don't have QA, and don't have release notes. Without structure, "improve the docs" becomes "rewrite the landing page for the fifth time this year" instead of fixing the ten pages driving the most user confusion.

This guide covers the signals that tell you what to improve, and the cadence that keeps improvement from becoming someone's side quest that never lands.

Why metrics matter

The five signals

1. Search queries returning zero results

The highest-leverage signal. Users typed something, your docs had nothing. Every zero-result query is either:

• A missing page you should write, or

• An existing page whose heading / alt terms don't match user vocabulary.

NookDocs's analytics surfaces this in Top searches. Target: drive zero-result queries to under 5% of total searches.

Weekly routine:

1. Open analytics → Top searches.
2. Filter to "no results" (column sorts zero first).
3. For each top query:
   - Does a page already cover this? (If yes → the page needs better H2s)
   - Is this a missing feature we should document? (If yes → write the page)
   - Is this a rare typo / joke query? (If yes → ignore)

2. High-bounce pages in the quickstart / tutorial path

Any page that's supposed to be step 1 → 2 → 3 of a flow, but where >50% of arrivers bounce, is broken.

Expected: /quickstart → /quickstart/step-2 → /quickstart/step-3
Actual:   70% of /quickstart arrivers never reach step-2

Diagnostics:

• Page too long? Scroll-depth tracking (if you have it) — do users reach the "Next" link? If they're bouncing before scrolling, the intro is failing.

• Broken example? Copy-paste a snippet from the page into a fresh terminal. Does it work? 10% of bounces are "the example doesn't work."

• Wrong prerequisites? The page assumes Node 20 but many users have 18. Explicit prereq list up front.

• Dense text? Tutorial pages suffer from walls of prose. Break into steps; add code blocks; add screenshots.

3. Support tickets with URLs

Every ticket that includes a link to a specific docs page is a signal that the page didn't answer the question.

Monthly routine:

Target: support ticket count per docs page should trend down over time. If it's flat or rising, the page isn't improving.

4. Feedback widget thumbs-down with comments

NookDocs's built-in feedback widget prompts readers for thumbs-up/down + a comment. Thumbs-down comments are direct user testing data you didn't have to run.

Patterns to notice:

• "Outdated" — screenshot / example / instructions don't match current UI. Fix and freshness-stamp.

• "Incomplete" — the answer stops before the reader's actual question. Add the missing step or edge case.

• "Wrong" — factual error. Fix urgently. Wrong docs erode trust faster than missing docs.

• "Confusing" — reader didn't know what to do after reading. Usually a voice + structure problem — see style and tone.

Aim to respond to every thumbs-down within a week during the first few months of shipping a page. After that, monthly review is enough.

5. Time-to-first-success

The most important metric and the hardest to measure. How long from landing on your docs to "the reader has something working"?

Proxies that work:

• Signup → first API call (if you're a SaaS API) — measurable in backend analytics.

• Signup → first successful deploy (if you're a dev platform).

• Landing → completion of the quickstart (if your quickstart ends with a clear "complete" signal, e.g. a success page or a redirect).

Benchmarks vary by product. For a dev-tool quickstart: under 5 minutes is great, 5-15 is fine, 15-30 is a concern, 30+ is a crisis.

The improvement playbook

Given a page that's clearly failing (high bounce + support tickets + thumbs-down), run this sequence:

The weekly review rhythm

30 minutes weekly, same day + time every week. Calendar block it.

Weekly rhythm > quarterly "docs sprint". A sprint ships 20 changes at once and you can't attribute impact to any one of them. Weekly ships 1 change you can isolate.

Quarterly audits

Broader lens, every ~12 weeks:

Metrics that DON'T matter (mostly)

When you have no metrics

Early-stage products often launch docs before any measurable traffic. In that case:

1. Ship the quickstart you're most confident in. Don't wait for data.

2. Watch 3-5 users complete it live. Zoom + screen share. One hour gives you more signal than a quarter of analytics.

3. Instrument early. Add analytics on day one. Even low-volume data compounds.

4. Cross-reference against support. Even 5 tickets a week are signal.

Metrics help once you have 1000+ sessions/week. Before that, direct observation + team dogfooding is higher quality.

Measure before AND after

The discipline that separates real improvement from theater: measure the SAME metrics before AND after. Don't just ship and declare victory.

Pre-change measurements (baseline)
  /quickstart bounce rate: 67%
  /quickstart → /quickstart/step-2: 33%
  Support tickets referencing /quickstart: 14 last month
  Thumbs-down count: 8

[Ship the rewrite]

Post-change measurements (2 weeks later)
  /quickstart bounce rate: 41% (-26pp)
  /quickstart → /quickstart/step-2: 59% (+26pp)
  Support tickets referencing /quickstart: 4 this month (-71%)
  Thumbs-down count: 2 (-75%)

Numbers grounded the hypothesis. Attribution is defensible. Next improvement cycle has baseline.

Common improvement mistakes

Related

• Analytics — the NookDocs dashboard these metrics come from

• Feedback widget — the thumbs-up/down collector

• Understand your audience — personas that inform what "better" means per page

• SEO for docs — search impressions as a metric source

• Maintenance — sibling guide on keeping docs fresh over time