How a docs team fixed the right pages by asking on the page itself

An open-source project has good documentation and a real problem: the install guide is subtly wrong. A step changed two releases ago, and now newcomers get stuck at the same point. People notice — there are grumbles on social media and a couple of confused questions in the community chat — but the maintainers cannot act on any of it, because none of the complaints say **which page**. "Your docs are out of date" is a feeling, not a bug report. So the wrong step sits there for months, quietly turning away every new user who tries to get started. Documentation lives or dies on this loop: a reader hits a confusing or wrong passage, tells the maintainers exactly where, and the maintainers fix it. Break the "exactly where" and the whole loop stalls. ## The problem: feedback without a location is noise Readers are willing to help. They will happily tell you a page is confusing. What they will not do is the archaeology required to make that help actionable — copy the URL, find the right contact channel, describe the problem, and note which section and which version. That is a lot of steps for someone who is trying to learn your tool, not audit your docs. So the feedback that does arrive is stripped of the one thing that makes it useful: the location. A maintainer reading "the API docs are wrong" has hundreds of pages and no idea where to look. A GitHub issue helps, but it asks a casual reader to have an account, understand your issue template, and switch context out of the docs entirely — friction that filters out most drive-by feedback, which is exactly the feedback that catches small, high-impact errors. The result is a strange imbalance: lots of readers notice problems, almost none get reported in a form you can fix. ## The fix: a per-page "Report an issue" link Put a small **Report an issue with this page** link in the footer of every docs page. It is a `mailto:` link, and its trick is that it pre-fills the current page path into the subject and body. The reader clicks, their email opens with the location already captured, and all they add is what was wrong. Because docs are usually built from a template or a static-site generator, you can inject the path automatically. In a templated site, drop the page variable straight into the link: ```html <a href="mailto:[email protected]?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Report an issue with this page </a> ``` Or set it with a line of script so it works on any page without templating: ```html <a id="docs-issue" href="#">Report an issue with this page</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:[email protected]' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` The generator on this site produces the encoded link; the script only swaps in the live path. Now every report names the exact page in its subject, and a maintainer can jump straight to the source file. ## Why on-page beats an issue tracker for this An issue tracker is the right home for a fix, but a poor front door for feedback. It demands an account, a context switch, and familiarity with your process — barriers that turn away the casual reader who just spotted a typo in a code sample. The `mailto:` link meets readers where the confusion actually happens: on the page, in one click, with no account. It captures the long tail of small corrections that would never survive the trip to a tracker. The two work well together. Reports arrive by email, pre-tagged with the page; a maintainer triages them and opens tracker issues only for the ones worth tracking. You get the low friction of email at the front and the rigour of a tracker at the back. ## Setting it up 1. Choose a docs inbox such as `docs@` that maintainers watch. 2. In the generator, set the recipient, a subject of "Docs issue: [page path]," and a body that prompts for what is wrong and what would help. 3. Add the link to your page template's footer, injecting the path with your generator's page variable or the small script above. 4. Route incoming mail by the "Docs issue:" subject tag so reports land in one place. 5. Close the loop: when you fix a reported page, a one-line reply to the reader turns a bug report into goodwill. ## What it saves The first saving is **maintainer time spent locating problems**. When every report names the page, you skip the detective work and go straight to the fix. A report that used to be an unactionable "something is wrong somewhere" becomes a two-minute edit. The second is **fewer stuck users**. Documentation errors compound: a wrong install step does not fail once, it fails for every newcomer until someone fixes it. Shortening the time from "a reader notices" to "a maintainer knows exactly where" means each bad passage turns away far fewer people. For a tool that grows by adoption, unblocking newcomers is growth. The third is **volume and honesty of feedback**. Because reporting takes one click and no account, more readers do it — including the ones who would never open a tracker issue. You hear about the small, embarrassing errors that erode trust, and you hear about them while they still matter. ## Make it even better - Auto-fill the **doc version or commit** alongside the path, so you can tell whether a report predates a recent rewrite. - Add the link to **404 pages** in your docs, where a missing page is itself useful signal. - Keep the address **obfuscated** so bots do not harvest it from thousands of public pages. - Offer a visible fallback for readers without a default mail app, such as a plain address or a tracker link. ## Key takeaways - Docs feedback without a location is noise; readers rarely do the work to attach one. - A per-page "Report an issue" `mailto:` link pre-fills the exact path, so every report is actionable. - On-page email captures the casual corrections a tracker filters out, then feeds the tracker for real fixes. - It saves maintainer time, unblocks newcomers faster, and surfaces the small errors that quietly cost trust. Build your own docs-feedback link in the [generator](/#generator), or copy the setup below.