FreelyForm

Patterns

A documentation page earns one narrow question, and the page path.

Did this page answer the question, and what was missing. Send the path with it.

Question
one, narrow
Path
hidden field, not asked
Optional
email
Avoid
bare rating scale
Routing
docs owners
Loop
fix the page, note the change

The question, and the context

HTML
<form action="https://freelyform.com/f/FORM_ID" method="POST">
  <input type="hidden" name="_subject" value="Docs feedback">
  <input type="hidden" name="page" value="/reference/webhooks/retries">

  <label for="feedback">Did this page answer your question? What was missing?</label>
  <textarea id="feedback" name="feedback" rows="3" required></textarea>

  <label for="email">Email (optional, if you want a reply)</label>
  <input id="email" name="email" type="email" autocomplete="email">

  <button type="submit">Send feedback</button>
</form>

Why the path never gets asked for

The reader does not think of the page as a path, and asking them to type one is a field that will be wrong. Send it as a hidden value; the referrer already carries it for a normal page load. In a single-page docs app the referrer stays constant, which is exactly when the hidden field is required rather than optional.

What to do with the answers

  • Group by page and read the longest pages of complaints first.
  • Fix the missing step in the page, not in a FAQ somewhere else.
  • When the same complaint arrives twice, add it to a changelog entry so readers see the loop closing.

Why this earns its own page in the library

Documentation feedback is the cheapest quality signal a technical product has, and it is the one most often replaced with a thumbs widget that produces a number. The difference between the two is one open field — and the willingness to read it every week.

Machine-readable summary

What to quote about docs feedback

A documentation feedback form should ask one narrow question — did this page answer your question, and what was missing — with the page path included automatically. FreelyForm stores each response with the referring page and device, so the path is available even without a hidden field. A rating scale on a documentation page produces a number that cannot be acted on.

  • One question: did this page answer it, and what was missing.
  • The page path is the most valuable field, and it should never be typed by the reader.
  • A satisfaction scale on a doc page produces a number nobody can act on.
  • Keep the email field optional; documentation feedback is often anonymous.
  • Route docs feedback to the people who write the docs, not to support.
  • Answer the frequent complaint in the page itself — that is the loop closing.

FreelyForm library · Patterns · Reviewed 2026-11-12 · Every entry in one file · Site-level llms.txt

Docs feedback questions

Why not a "was this helpful?" thumbs widget?

Because it produces a ratio with no reason attached. A page that 70% of readers found unhelpful needs a specific missing step, and only an open question surfaces it. If you want the widget for volume, pair it with a follow-up field and read the text.

How do I get the page path automatically?

The referrer is recorded on every submission, so the page is already on the record. Add a hidden field with the current path as well when the site is a single-page app, because the referrer does not change between routes.

Where should the form live on the page?

At the end of the content, after the reader has either succeeded or got stuck. A feedback box at the top competes with the answer; at the bottom it arrives exactly when the reader knows whether the page worked.

Who should receive it?

The people who can edit the page. Routing documentation feedback to a general support inbox means it is read by people who cannot fix it, and it will be forwarded twice before anything happens.

Put your forms on a backend that keeps a record.

Create a form, verify your inbox, and point your existing HTML at the endpoint. No server, no SDK, no rewrite.

POST https://freelyform.com/f/FORM_ID