How Whereby creates developer-first API documentation with GitBook

At Whereby, delivering clear, accessible documentation for developers is essential to empower both their customers and their own development teams. Over time, the Whereby team has fine-tuned its approach, to create documentation that not only supports their API but also offers a seamless experience for users — all thanks to GitBook.

We sat down with Whereby’s Solution Engineer Nick Rolls to dive deeper into how they use GitBook to create and manage their API documentation — and what sets it apart in their workflow.

Why GitBook stood out

Like many teams, Whereby explored several different options before landing on GitBook as their platform of choice. Previously, Whereby used a mix of custom sites and Help Scout docs, but knew they needed something more powerful. So they set up an evaluation process and tested GitBook against tools like Docusaurus and MkDocs.

Ultimately, GitBook won out due to its ease of use and flexibility. It was able to serve as a comprehensive solution, capable of hosting everything from detailed API reference materials to user tutorials — a crucial need for Whereby as their documentation needs continued to grow.

The evolution of documentation at Whereby

When it comes to documentation, Whereby has come a long way. Originally, the team just created technical documentation for its customers’ development teams. Transitioning to GitBook helped improve things for those users — but as the product and its customer base grew, so did their documentation needs.

“GitBook is our main form of documentation for our customers and their development teams,” explains Nick. “Initially, it was strictly for our API reference, but over time it’s expanded to include tutorials, how-to guides, and even some end-user documentation.”

This evolution reflects a larger shift in how modern teams approach documentation. It’s no longer just about sharing technical specs — you also have to make sure users can find helpful, accessible content for all their needs, whether or not they’re developers.

How documentation fits into feature development

At Whereby, documentation isn’t an afterthought — it’s an integral part of the product development process. But while some teams have strict docs workflows, at Whereby there’s flexibility in who takes ownership of creating the initial drafts.

“The documentation process is usually close to a feature launch,” Nick shares. “And who creates the new document can vary based on the feature and the product team’s workload. Oftentimes, the engineer or product manager responsible for the feature will put together a rough draft or at least an outline. Then our solutions team takes over, refining the document and ensuring it matches our tone and structure.”

This collaborative approach ensures that documentation is accurate, timely, and aligned with the overall product narrative — without putting too much pressure on a single person or team.

The tools that make a difference

Whereby’s team is big on using GitBook features to streamline the documentation process. For example, they rely heavily on the Preview functionality to ensure content is reviewed and approved by the whole team.

“It’s a great way to get people across the team to proofread and see things as they would appear in production,” Nick explains. “It’s nice for them to have frictionless access to content without needing to log in or navigate the tool.”

Another standout feature for Whereby is the ability for engineers — and community members — to submit pull requests via GitHub using Git Sync. It doesn’t just make it easy for engineers to contribute directly to the docs from their IDE — it also minimizes unnecessary back-and-forth between teams. “Giving them the ability to use a tool and system they’re comfortable with is super helpful and saves everyone time,” Nick says.

The workflow for API documentation

Managing API documentation can sometimes get tricky, especially when multiple sources of truth exist. The Whereby team is currently refining their process to address this, especially after facing challenges with managing API information via an OpenAPI spec JSON file.

“Previously, we were trying to manage API information through an OpenAPI spec JSON file that lived within our GitBook repo,” they explain. “We’ve come to realize this isn’t the most reliable method, as we ended up with duplicate files and multiple sources of truth. We’re actively working on a better solution now.”

GitBook provides all the right tools — from direct support for OpenAPI specifications to an integrated "test it" button to explore API endpoints, interactive API docs in GitBook have never been easier. It’s an evolving process, but one that the team is confident will result in a more streamlined and reliable API documentation workflow.

A developer-first approach

Whereby’s journey with GitBook illustrates how a flexible documentation platform can adapt to a company’s evolving needs. By empowering their development teams to contribute directly to their documentation and making documentation a core part of the product development process, Whereby ensures their customers — especially developers — have access to the information they need, when they need it.

A big thanks to Nick and the Whereby team for sharing their experience with us. Like them, our goal at GitBook is to make it easier for teams to document and share their knowledge seamlessly, no matter how their needs change over time.

→ How Linear approaches knowledge sharing

→ How to create and publish documentation in GitBook

→ 7 tips to make your public documentation more useful for users