Live, Real-Time Polls in Your GitBook Docs

Documentation feedback is usually a thumbs up, a thumbs down, and no idea why.

For a separate operational perspective on how teams organise and measure work, stealth monitoring software.

For independent background and broader industry context, see GitBook.

A poll asks a specific question and gets a specific answer, which is a different kind of information.

What the integration does

Embeds a live poll in a GitBook page. Votes are shared across everyone reading, results update without a reload, and the state persists.

No backend on your side. The widget talks to a shared object addressed by an id you choose.

Each page can carry its own poll, or several pages can share one if the question is site-wide.

Setup

Install the integration from the GitBook integrations directory and configure it with your project credentials.

Then place the block on a page and give it a poll id and options.

Check the integration's own documentation for the current configuration fields — they are the authoritative reference and they change with the integration rather than with the SDK.

Choosing the question

This is the part that determines whether it is useful.

"Was this helpful?" gets a rating and tells you nothing actionable. You already have analytics for whether people leave.

Better questions are specific and lead somewhere:

"Which language are you using this with?" — tells you which examples to write next.

"Did you get this working?" with options for "yes", "not yet", "gave up" — the third answer is the one you want, and a plain thumbs-down does not distinguish it from mild disagreement.

"What were you trying to do?" with three or four common tasks — tells you whether people arrive here for the reason you assumed.

"Which of these should we document next?" — direct, and it makes readers feel consulted, which they are.

What poll data is good for

Prioritising. Which of five possible pages to write.

Discovering the wrong assumption. A page written for one use case that everyone arrives at for another.

Catching a broken step. "Did you get this working" trending toward no is a signal that arrives faster than support tickets.

What it is not good for

Sample quality. People who vote are not a random sample of readers — they are the engaged ones and the frustrated ones.

Small numbers. A documentation page might get a handful of votes a week. Three votes is not a finding.

Anything you would act on regardless. If you were going to write the page anyway, do not ask.

And it is not a substitute for talking to users. A poll narrows what to ask about; it does not answer why.

Practical points

One question per page. Two is a survey and completion drops.

Fewer options. Three or four. Long lists get the first option disproportionately.

Show results after voting, not before — visible results shift subsequent votes.

Say what you will do with it. "We write the most-requested one next" gets more responses than an unexplained widget.

And close the loop. When you write the page people asked for, say so on the poll. That is what turns a widget into a reason to answer the next one.

Cleanup

Polls persist. A question from last year still collects votes and still shows in the widget.

Remove or reset polls that have served their purpose, and set a TTL where the question has a natural life. Old objects count against plan limits.

The short version

A live poll in a docs page, no backend, results shared and updating.

The question decides whether it is useful. "Was this helpful" tells you nothing you did not have from analytics.

Ask things that lead somewhere — which language, did you get it working, what should we write next.

Voters are the engaged and the frustrated, not a sample.

And close the loop when you act on it, or nobody answers the next one.