The Annotated FAQ

By judell | 28 January, 2016

A few weeks ago we published a frequently-asked questions page. In the time-honored tradition of the internet FAQ, we want ours to be a living document that evolves as we add features and interact with users.

That tradition is often more honored in the breach than the observance, but we have an ace up our sleeve: annotation. Our FAQ-building process starts upstream in Zendesk, the customer service tool we recently began using to wrangle support requests from several channels into a common pool. Unlike Google’s mail and forum tools, which currently thwart annotation, Zendesk makes standard web pages that we can annotate with Hypothesis.

There are two ways such annotation might be useful. First, to discuss our responses before sending them. Second, to tag support requests in order to categorize and quantify them.

Zendesk already supports discussion so we use it for that purpose, there’s no need to reinvent wheels. But our version of Zendesk doesn’t include tagging, so we use Hypothesis tags to categorize support requests. We do our support tagging in a private group that we can then query, using the Hypothesis API, to show categories and their frequencies.

The tags we’re using correspond roughly to topics in the FAQ. As those categories stabilize over time, they’ll become a test case for a feature mentioned on our roadmap: controlled tag vocabularies. Meanwhile the loose categorization helps us quantify the need for various product improvements, of course, but also for better explanations in the FAQ.

We support users on email, in a forum, and on Twitter. Here’s a recent Twitter request:

@judell @dr_jdean Whats best way to “reset” pdf? After annotating doc for four semesters it’s time to wipe slate clean. Too slow and yellow.

I ran a quick test and came up with this answer which I’ve included at

How do I “reset” a PDF to make fresh annotations?

If using Acrobat, export to Postscript and create a new PDF from the exported file.

There’s always more to the story, of course, and that’s where you come in, dear reader — and, we hope, Hypothesis user. Do you know a different or better way to reset a PDF using Acrobat? Would you like to share a method that works (or doesn’t) using a different PDF writer? Annotate the FAQ and tell us!

Share this article