Documentation That Converts: Technical Writing That Drives API Adoption

This is Part 4 of "The Developer Advocate's Journey" series. Two documentation rebuilds, two very different starting problems, and the same underlying lesson: docs don't fail because they're incomplete, they fail because nobody designed them to move a developer from "curious" to "integrated."

Docs Aren't a Reference Shelf, They're a Conversion Funnel#

Every team I've worked with already believes documentation matters. Almost none of them treat it like a funnel with a drop-off rate.

Reference material tells a developer what an endpoint does. Conversion-focused documentation gets them from "I found this page" to "I shipped an integration" with as few dead ends as possible. Those are different design problems, and most documentation only solves the first one.

I've rebuilt documentation twice from that lens - once for the Freshworks Developer Portal, once for Bazaarvoice's Developer Console and API Gateway. Neither rebuild started as a writing project. Both started as an admission that the existing docs were actively losing developers.

The Freshworks Rebuild: Seven Sites, Zero Shared Path#

By the time I joined Freshworks as Lead Developer Advocate, the developer documentation for the Neo Platform was spread across seven separate product sites - Freshdesk, Freshservice, Freshchat, Freshworks CRM, Freshteam, and more - each covering developers building apps with the Freshworks CLI Toolkit (FDK).

The underlying stack was the real problem: plain HTML pages generated from Ruby files through a Middleman server, a setup that had already been deprecated since 2019. Every update meant a manual build. Every product had its own navigation, its own component patterns, its own idea of what a "getting started" page should look like. A developer building across two Freshworks products effectively had to relearn how to read the docs twice.

We didn't rewrite content first. We rebuilt the pipeline: Markdoc for authoring so non-engineers could still contribute structured content, a shared React component library so every product finally rendered code samples, tables, and callouts the same way, and a Jenkins-based CI/CD pipeline so a doc update shipped like a code change instead of a manual export.

The part that actually drove adoption wasn't the migration itself - it was that a developer building a Freshdesk app and a Freshworks CRM app now hit the same getting-started pattern, the same component behavior, the same search. Consistency removed the relearning tax that had been quietly taxing every cross-product developer.

The Bazaarvoice Rebuild: Docs That Drifted From the Code#

At Bazaarvoice, the problem looked different but rhymed. The API Gateway and Developer Console documentation was written after the API shipped, by whoever had time - which meant it drifted from the actual endpoints almost immediately. Enterprise partners integrating through the Developer Console would hit a documented parameter that no longer matched the live response, and the fix was always a support ticket, never a doc fix.

The onboarding path made it worse. New developers landed on comprehensive reference material with no clear "start here," so the first real decision they had to make - REST or GraphQL, which SDK, which auth flow - was the first thing they saw, before they'd had a single successful call.

The fix was documentation-first API design: the OpenAPI spec came before the code, and reference documentation generated directly from that spec instead of being hand-maintained afterward. We paired that with an interactive sandbox on the Developer Console so a developer could make a real call with realistic test data before committing to an integration path, and we refreshed the Java, Python, and JavaScript SDKs so the code examples in the docs actually matched what the SDKs shipped.

None of that came from better prose. It came from removing the gap between what the docs said and what the API actually did, and from giving developers something to try before asking them to read.

The Pattern Underneath Both Rebuilds#

Strip away the specific stack, and the same four moves show up in both rebuilds:

Four techniques carried across both companies, even though the products, languages, and starting problems were unrelated:

1. Put a spec (or a shared component system) at the center, not a wiki page. Bazaarvoice generated docs from OpenAPI. Freshworks generated pages from a shared Markdoc + React pipeline. Different tools, same principle: content shouldn't be hand-maintained in a place disconnected from the thing it describes.

2. Give developers something to try before something to read. The Developer Console's interactive sandbox and the Freshworks Developer Portal's live component previews both exist so the first interaction is hands-on, not a wall of reference text.

3. Componentize once, reuse everywhere. Freshworks' 38 reusable documentation components and Bazaarvoice's refreshed Java, Python, and JavaScript SDK examples both solved the same problem: write the pattern once, and every product or endpoint that needs it inherits it for free.

4. Automate the pipeline so docs ship at the speed of code. Jenkins-based CI/CD for Freshworks, automated OpenAPI-driven generation for Bazaarvoice - in both cases, the moment docs stopped requiring a manual step, they stopped falling behind.

Your Documentation Conversion Audit#

Next in the series: "Measuring DevRel Impact: Beyond Vanity Metrics"

Rebuilt documentation at your own company? Share what actually moved the adoption numbers - I read and respond to every comment.