blog: key metrics for docs (#161)

Author: adamaltman

blog/images/key-metrics-for-docs.png

@@ -0,0 +1,181 @@
+---
+template: '../@theme/templates/BlogPost'
+title: Beyond the North Star
+description: "Moving beyond the North Star to Orion's Belt of key metrics for docs: Acquisition, Adoption, and Deflection."
+seo:
+  title: Key Metrics for Docs
+  description: "Moving beyond the North Star to Orion's Belt of key metrics for docs: Acquisition, Adoption, and Deflection."
+  image: ./images/key-metrics-for-docs.png
+author: adam-altman
+date: 2025-11-04
+categories:
+  - tech-writers
+  - developer-experience
+image: key-metrics-for-docs.png
+---
+
+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.
+
+## Acquisition: Bringing new developers into orbit
+
+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.
+
+## Adoption: Deepening engagement and usage
+
+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.
+
+## Deflection: Reducing friction and saving support costs
+
+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 value expansion loop
+
+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.
+
+## Getting started: Choosing your first metric
+
+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
+
+## Conclusion: Aligning your own belt of stars
+
+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.