How Scale AI democratized their docs with ReadMe

Learn how ReadMe has become a source of truth for their API for customers and internal teams alike.

kanad’s Slack Avatar
Now that is a developer experience that will... "scale"!
kanad’s Slack Profile
Kanad Gupta
Developer Advocate
Actual excerpt from our company Slack channel#nicedocs

Many API teams are focused on building an ecosystem around their core product: extending functionality, building integrations, syncing data, and more.

But for API-first companies like Scale AI, their API is an integral part of their user experience. As such, they’ve strategically invested in their API onboarding and support processes to help customers realize the Scale’s value as easily as possible — and that starts with their ReadMe hub.

I don’t want to imagine a world without our documentation. It’s the source of truth for Scale’s product knowledge for our engineering team, for our customers, for our solutions engineers. Without it, we’d be stuck. It’s a critical piece of our go-to-market strategy and enables us to move faster. Shaun VanWeelden, Head of Field Engineering

Outgrowing Slate as a solution

Shaun VanWeelden, Head of Field Engineering at Scale, runs a team of seven Field Engineers who own this high-touch experience for their customers. Beyond owning Scale’s documentation, they think holistically about the customer’s technical experience with Scale: from creating SDKs for sending data to Scale to guiding and troubleshooting each customer’s integration.

Like many startups, they started out with simple API docs built with Slate. As an open-source tool, it was easy and inexpensive for them to get started and served them well in the early days. But as Scale continued to, well, scale (we can’t resist!), Shaun and his team started see its shortcomings:

  • Only engineers could make changes to the docs through GitHub, creating a bottleneck for others wanting to make updates and a time-sink for engineers.
  • Slate lacked native search capabilities, which was especially painful as Scale continued to expand its functionality.
  • Slate was limited to an API reference only, without the ability to add more guides and tutorial content around other parts of the platform.

They also wanted to make their docs more interactive, to get users trying out API calls as quickly as possible. Slate’s static approach to documentation didn’t allow for the dynamic experience they envisioned.

Investing in their developer experience

Instead, Shaun and his team wanted to create a scalable hub for documentation that would encourage users to jump in and try things out. They also wanted to democratize their docs so that anyone at Scale could easily contribute — while also saving time for engineers to focus on higher impact tasks.

For us, it’s really a buy vs. build decision. We’d rather leverage a partner whose whole focus is documentation and developer experience, rather than take on that effort and invest hundreds and hundreds of hours in-house. Shaun VanWeelden, Head of Field Engineering

When looking at potential solutions, ease of use was a key priority without sacrificing the high design standards that Slate upholds. ReadMe brought together a collaborative editing system, design customization options, and interactivity that would enable users to try out API calls in real time. For Shaun’s team and key stakeholders from product, design, and go-to-market teams, this was the combination they’d been looking for.

Designing their hub

Because ReadMe would allow them to add new guides and tutorial content beyond their API reference, they first mapped out the new content architecture and round-robined articles across the team to write. They invested heavily in this content effort as their docs are not just critical for customer enablement — they’re also a key marketing asset that prospects use to understand whether Scale is the right solution for them.

At the same time, Scale’s design team ran a hackathon project to build out the design for their hub. They ended up building a custom front-end to align with Scale’s brand and syncing their content using ReadMe’s API, similar to a headless CMS implementation. This unique approach gave them complete creative control while enabling the easy editing and interactive developer experience they were looking for.

One of the things that has been really impactful is the interactivity that ReadMe provides. We’ve made our docs fully interactive, so developers can make API calls without actually having to write code: like a “no-code” editor for our API. Shaun VanWeelden, Head of Field Engineering

A source of truth for Scale

Beyond the look and feel of their new hub, one of the biggest transformations since moving to ReadMe has been a sense of empowerment for both developers and internal teams.

One of the things that’s paid dividends for us is writing guides for how to make updates with ReadMe. When people feel empowered to make changes to the documentation without needing me or the team, they’re more likely to take the time to do it. Shaun VanWeelden, Head of Field Engineering

As an API-first platform, their ReadMe hub is a source of truth for teams across the company to reference or test functionality to help answer customer questions more efficiently. Because it’s easy for anyone to make updates directly in ReadMe rather than relying on engineering resources, everyone can be confident that the content in their docs actually reflects the latest and greatest improvements in the Scale platform, rather than falling out of date. They’ve even created a #docs channel in Slack where teammates can quickly share feedback or ask questions to keep improving.

For developers, the difference has been night and day. The Scale-branded experience makes a great first impression and also makes their documentation hub feel like an integral part of the product. Native search allows users to find what they’re looking for quickly, and having product guides and the API reference together in one place gives them a complete picture of the Scale platform. Going forward, Shaun and his team are confident they’ve found a solution that will scale (!) with them as they continue to grow.

When you’re an API-first platform, I don’t think you can overstate the importance of documentation. It’s the way forward for support issues, for engineering to keep improving the API, and for customer-facing teams to sell and implement effectively. It’s worth the time to get it right. Shaun VanWeelden, Head of Field Engineering