Most documentation teams struggle to measure success. They track page views and bounce rates, but these metrics don't tell you whether your docs are actually driving business value. Are they helping developers discover your APIs? Are they enabling deeper integration? Are they reducing support burden?
The problem isn't that documentation success can't be measured—it's that many teams don't know which metrics matter, or how to connect them to real business outcomes. When you're only tracking vanity metrics like page views, you might see high numbers but still struggle to justify your documentation budget or understand where to invest next. You're flying blind without a clear picture of how your docs contribute to developer success or business growth.
At Redocly, we've noticed a pattern with our customers. When organizations invest in their developer experience, they're usually trying to move the needle in three measurable areas: acquisition, adoption, and deflection. Each one can be tracked, valued, and optimized. Align these three "stars" and you'll find they point the way toward something bigger: a self-reinforcing loop of value expansion.
For centuries, travelers have looked to Orion's Belt — three bright stars lined up in the night sky — to find their way. Each star is striking on its own, but together they create a guide that points the way forward. Your documentation metrics work the same way.
You can't grow without new developers discovering and trying your APIs. Acquisition is all about lowering the barriers to entry and making your documentation discoverable.
What to measure:
- Unique developers signing up or authenticating for the first time
- Growth in developer portal traffic (especially from organic search)
- Number of successful completions of quickstarts or "hello world" tutorials
Experiments to try:
- Optimize API documentation for SEO so developers find you faster
- Showcase successful integrations with tools like Revel to build trust
- Simplify onboarding with clearer quickstarts and fewer steps to first API call
When acquisition shines, you expand your developer audience and create more opportunities for adoption.
Getting developers in the door is only the first step. Adoption measures how well they integrate your APIs into real-world workflows and keep coming back.
What to measure:
- Average number of APIs or endpoints used per developer or team
- Trial-to-production conversion rate
- Return visits to your portal and engagement with tutorials
Experiments to try:
- Offer richer examples, SDKs, and tutorials tailored to developer roles
- Make navigation intuitive with well-structured documentation (Realm, Reef)
- Personalize experiences based on developer history or role
Adoption transforms curious developers into active builders. And active builders create fewer repetitive support requests — which leads directly to our third star.
A mature API program doesn't just attract and engage developers — it frees up your support team by giving developers answers before they have to ask.
What to measure:
- Reduction in support tickets per integration
- Percentage of developer questions answered via documentation or search
- Satisfaction scores on docs or self-service flows
Experiments to try:
- Improve search relevance with AI-powered results
- Add guided troubleshooting flows for common errors
- Expand FAQs and real-world examples based on actual support logs
Effective deflection is not about avoiding support — it's about empowering developers to move faster and succeed on their own.
The real magic happens when these three outcomes reinforce each other:
- Strong acquisition brings in more developers, creating more chances for adoption.
- Increased adoption means developers become self-sufficient, reducing ticket volume.
- Better deflection frees up your teams to reinvest in acquisition and adoption.
This cycle compounds over time, creating what we call a value expansion loop. Each aligned improvement multiplies the impact of the others.
Here's how it works in practice:
Example 1: SEO improvements ripple outward
When you optimize your documentation for search (acquisition), more developers discover your APIs. As more developers find you organically, a higher percentage complete your quickstart guides. Developers who successfully complete quickstarts are more likely to move to production (adoption). In production, they're already familiar with your docs, so they search your portal before opening tickets (deflection). With fewer tickets, your support team can create more comprehensive troubleshooting guides, which improve SEO and start the cycle again.
Example 2: Better search creates compounding value
You improve your documentation search with AI-powered results (deflection). Developers find answers faster, reducing frustration and increasing satisfaction. Satisfied developers are more likely to integrate additional APIs (adoption). They also share your APIs with colleagues, bringing in new developers (acquisition). More developers mean more diverse search queries, which helps you identify gaps and improve search relevance further.
Example 3: Adoption-focused improvements create momentum
You add role-based tutorials that help developers move from trial to production faster (adoption). Developers who reach production are more engaged and use multiple endpoints. They return to your docs regularly to discover new capabilities. This increased engagement signals to search engines that your content is valuable, improving organic rankings (acquisition). Engaged developers also provide feedback that helps you create better FAQs, reducing future support tickets (deflection).
The key insight: these metrics aren't isolated goals. They're interconnected forces that amplify each other when aligned. Focus on one, and you'll naturally see improvements in the others—but only if you're measuring all three.
You don't need to measure all three metrics perfectly from day one. Start with the one that aligns best with your current organizational priorities.
Choose Acquisition if:
- You're launching a new API or developer portal
- Your primary goal is expanding your developer base
- You're struggling to justify documentation investment (acquisition metrics show clear ROI)
- Marketing or growth teams are your primary stakeholders
Choose Adoption if:
- You have steady traffic but low engagement
- Developers sign up but rarely move past initial setup
- Your goal is increasing API usage or revenue per developer
- Product teams need to understand developer integration patterns
Choose Deflection if:
- Support teams are overwhelmed with basic questions
- You're under pressure to reduce support costs
- Developers frequently ask questions that should be answerable in docs
- You want to demonstrate clear cost savings from documentation
Once you've chosen your starting point, set up baseline measurements. Track your chosen metric for 4-6 weeks to establish a baseline. Then run one focused experiment—maybe optimize a key page for SEO, add a troubleshooting guide, or improve your quickstart flow. Measure the impact, learn from it, and iterate. As you see improvements in your primary metric, you'll naturally start noticing how it connects to the other two.
The tools you'll need are simpler than you might think:
- Analytics platforms (Google Analytics, Mixpanel, or similar) for acquisition metrics
- API usage data and authentication logs for adoption metrics
- Support ticket systems and search analytics for deflection metrics
- Most importantly: a shared dashboard where your team can see all three metrics together
Like Orion's Belt, acquisition, adoption, and deflection are easy to recognize when you know where to look. Alone, each metric matters. Together, they create alignment — guiding your organization toward sustainable growth and developer success.
The challenge (and opportunity) is to measure, experiment, and realign continuously. When you do, you'll see that these three stars don't just point the way — they create a loop that expands value for both your developers and your business.
Start by picking one metric that aligns with your current priorities. Measure it. Experiment with improvements. Then watch how strengthening one star helps illuminate the path to the others.