How we revamped Batch’s documentation

At the beginning of this year, Batch undertook a project to revamp its documentation, now available at doc.batch.com.

This was a cross-functional project and not as straightforward as it may seem. So we wanted to take the time to share our experience to help potential software publishers facing a similar project make the right choices.

As a Batch customer, this article also helps you understand the changes and benefits of this evolution. It takes the form of an interview with Selma, Solution Architect, who led the project.

Selma, why this revamp?

Two main reasons:

• Batch’s documentation was split between two places: doc.batch.com, which hosted SDK, API, and Dashboard documentation, and help.batch.com, our Help Center, which contained articles addressing major client questions on all topics. It wasn’t easy for clients to navigate between the two. We were serving both business and technical personas with our documentation, and they didn’t know where to go. There was also a lot of duplicate content across both spaces.

• The doc.batch.com space had to be edited directly through GitHub. It was an austere and rather slow interface when it came to publishing. It didn’t encourage teams to contribute. The help.batch.com space was based on Intercom Pages—a much easier interface to use. This ease led to a lot of content being created as help articles. A massive volume of articles was generated, creating maintenance challenges.

How did you start the project?

We began with a needs analysis phase, interviewing a large number of clients, partners, and internal users. This helped us avoid biases from our initial perceptions. We also benchmarked competitors and documentation styles we admired. This gave us a broad base to build a strategy and define success KPIs.

Then we defined a retro-planning of the tasks to complete and set up a routine of regular working sessions with representatives from all involved teams.

We also put in place a way to keep the project sponsors informed through specific sync points.

How did you structure the documentation?

Before choosing the right tool, we defined the documentation structure we wanted. The major challenge: bringing together very diverse content on the same portal. We chose a well-known documentation framework — Diataxis (which means “organization” in Greek).

This allowed us to structure content according to:

• Reader objectives:

  • Get started with the “Getting Started” section,

  • Solve a specific problem and learn with the “Guides & Best Practices” section,

  • Integrate Batch with third-party tools via the “Integrations” section,

  • Discover new features in the “Release Notes” section,

  • Use APIs and SDKs via the “APIs & SDKs documentation” section.
    

• User persona:

  • New business users are directed to “Getting Started,”

  • Experienced business users are directed to “Guides & Best Practices,”

  • Tech users are directed to “APIs & SDKs documentation”.

You chose a dedicated tool—why?

We defined criteria for selecting the tool(s) that would allow us to implement our vision.

Some key criteria:

• Ease of use, since contributors come from many teams: CSM, Onboarding, Customer Care, PM, Tech, etc.

• Effective API documentation capabilities for the technical personas, especially the need for good OpenAPI integration.

• A single place to host everything—from technical documentation to business content, including video walkthroughs.

• A clear view of product innovations in a Release Notes section.

• Collaborative and validation features that are not too complex but still present, to avoid having to work outside the tool.

We explored various options: using a CMS, open-source frameworks, flexible tools like Notion, or going with a product documentation-specific tool.

Without going into detail, we favored an approach that gave us maximum speed while meeting our key criteria—and staying within budget, of course.

We also considered some additional factors. For instance, the tool we chose, GitBook, allows users to interact with Batch’s new centralized documentation as they would with ChatGPT. These AI features empower our clients to be more autonomous by leveraging cutting-edge GenAI technology. Support was also important—GitBook has a strong, responsive European presence.

What are the first results of this migration?

The new centralized documentation went live in Q1 2025 and has grown significantly in Q2. We’re already seeing tangible results.

Internal users are very satisfied with the tool—it’s both simple and powerful. This has led to higher adoption and fresher content.

Clients have embraced the AI-powered search to explore the documentation—we’re seeing usage stats soar. We’re also learning a lot from the queries submitted.

It’s still early to assess the achievement of our longer-term KPIs, such as a drop in Level 1 support requests or clients telling us they couldn’t find information in the documentation.

We’re also aiming to improve Batch’s SEO in the medium term. In a few months, we’ll survey clients both qualitatively (via interviews) and quantitatively (by asking them to rate the documentation). We hope for very positive feedback!

And what’s next?

For the documentation project, we still need to shut down help.batch.com, which we’ve kept in place during the transition. That will happen at the end of July. After that, redirects will ensure users with bookmarked help.batch.com links land on relevant pages on doc.batch.com.

Mégane, Senior People Partner at Batch, is now working on developing a Learning Management System (LMS)—an extension of the documentation so our clients and partners can learn to use Batch autonomously through high-quality content. It will be linked to a full revamp of our certification program. We’ll be happy to share more about that later!