What we noticed: how people find our changelog
We’ve been shipping a lot this year and putting more work into our changelog to keep up, which got us wondering how people actually find it. The daily traffic made the answer pretty clear. From August to October, more than half of the changelog’s human views came in on just eight days, and each of those days lines up with a newsletter send or our docs quality launch. The nine days we published new changelog entries looked like any other day.
That made sense, since the newsletter is the main place we link to the changelog. But while digging into those spike days, something looked off. On a normal day, the changelog gets slightly more visitors on Macs than on Windows. On email days, Windows views shot up to between two and six times the Mac count, and far fewer of those visitors clicked through to a second page.
That pattern fits email security scanners. A lot of companies run tools that open every link in an incoming email to check it before anyone reads it, and in analytics those visits can look exactly like a person. When we compared click-through rates on email days with normal days, roughly half of a big email day looked like scanners, and for a minute the spikes felt a lot less impressive.
The people who are left are still a big number, though. Even after taking the scanners out, we estimate that about eight times as many people read the changelog on launch day as on a normal day. The newsletter really does send readers to the changelog, and we’d like to try reaching them in other places too, like a banner on the docs or a pointer from GitBook Assistant.
What we changed: we added a “New” label, and the banner did the work
On Oct 6, we added “New” labels in the sidebar next to two pages from the docs quality launch, Content gaps and Broken links. By mid-October, Content gaps was getting about four times as many views a day as before, and visits arriving from elsewhere in our docs were up more than twentyfold. It looked like the label was working.
Then we looked at where people were actually clicking. GitBook’s analytics events note where on the page each link click happened, such as the sidebar, the page content or the banner, so we could count sidebar clicks on Content gaps on their own. They didn’t budge. Style guide got its own label the next day and showed the same flat line.
The traffic was coming from the top of the page instead. On the same day the labels went in, the announcement banner across our docs switched from promoting our MCP server to promoting Content gaps. Over the next four weeks, the banner sent Content gaps 10 to 17 times as many clicks a week as the sidebar had before the label, and the sidebar didn’t move.
We shipped two changes pointing at the same page on the same day, and the page views had no way of telling them apart. If your analytics show where on the page a click happened, that’s the first thing we’d check before giving any one change the credit. And if you have something you want people to find, try the banner first. On our docs, at least, it did far more than a label.
What’s next: getting our guides read
Content gaps checks support conversations and GitBook Assistant questions against our docs, and on our own site it flagged a topic we’d missed: what to do if you lose your authenticator app. Since June, we’ve had 15 support conversations from people locked out for this reason. In October, two more people asked Assistant, which couldn’t fully answer either one. Our docs didn’t mention two-step authentication anywhere.
GitBook doesn’t use recovery codes, so the only way back in is for Support to confirm the account owner and reset it. Better docs won’t make these requests go away, but they can get people to that point quickly. We’ve added a two-step authentication section to the Personal settings page, with an FAQ built from the questions people actually asked. The finding also went beyond the docs: our product and engineering teams are now discussing whether GitBook should offer a self-serve way to recover.
We’ve saved these numbers as our baseline. If the section works, Assistant will answer this question in full, and support messages will shift from “I’m locked out, what do I do?” to “I lost my authenticator, please reset two-step authentication on this account.” We’ll report back in a future issue.
About the data
Everything here comes from GitBook Insights for gitbook.com/docs between August and October 2026, pulled through the Events Aggregation API. The daily views are in the Insights dashboard; the click-position and click-through numbers come from the API. “Human” means visits without a bot or agent flag, which, as the changelog numbers show, still lets some machines through. In the charts, a typical day is the median day from August to October, and the sidebar baseline is its average week before the label went in. Dates for our own changes come from the Git history of our public docs repo.
