If you’ve tuned into this blog for long enough, you’ll notice that we’re pretty big on using and stress-testing our own products (“dogfooding”) at Cloudflare.
That applies to our security team, product teams, and – as my colleague Kristian just blogged about – even our documentation team. We’re incredibly excited to be on the Pages platform, both because of the performance and workflow improvements and the opportunity to help the platform develop.
What you probably haven’t heard about is how our docs team uses dogfooding – and data – to improve our documentation.
Dogfooding for docs
As a technical writer, it’s pretty common to do the thing you’re documenting. After all, it’s really hard to write step-by-step instructions if you haven’t been through those steps. It’s also a great opportunity to provide feedback to our product teams.
What’s not as common for a writer, however, is actually using the thing you’re documenting. And it’s totally understandable why. You’re already accountable to your deadlines and product managers, so you might not have the time. You might not have the technical background. And then there’s the whole problem of a real-world use case. If you’re really dedicated, you can set up a personal project… but it’s hard to replicate real-world situations and even harder to simulate real-world motivation.
And that brings me to one of the coolest parts of our docs team. We actually manage the Cloudflare settings for our docs website, developers.cloudflare.com. There’s technical oversight from other teams as needed, but that means we’ve directly been involved in:
- Creating various rules to improve visitor experience and SEO ratings (forwarding, transform, bulk redirects).
- Enabling and tailoring bot protection.
- Using Cloudflare site analytics to identify needed redirects.
- Setting up Cloudflare Tunnels for pre-release reviews.
When we use our own products, it makes us part of the user journey. We know quite viscerally what it’s like when you accidentally break an internal tool with Bot management… because we’ve done it (and profusely apologized!). We know what it’s like to spend a few hours crafting a Transform Rule and realize that – for a specific use case involving search engine crawlers – we needed a Forwarding Page Rule instead.
Using our own products gives us a chance to dogfood our docs as well. We realized that we needed to add a page to the 1.1.1.1 docs because several of us set it up on our home devices and didn’t know whether it was working or not. Same thing with the Cloudflare Tunnel docs. When we use the thing, it’s easier for us to help others use it too.
Data for docs
Beyond our own experience – and even beyond the feedback we get through our open-source content strategy – we also look at quantitative data to identify gaps and potential improvements in our docs.
One of the easiest ways to identify gaps is to look at internal search data. When folks are searching from within our docs, are they leaving to view pages within other Cloudflare content sources (Community, Learning Center, etc.)? And does that page conceptually belong in our docs? We’ve used those two questions to identify and correct several gaps in our documentation, such as new pages on creating subdomain records, Cloudflare Ray IDs, and more.
External search data also informs our content strategy. When folks are coming into Cloudflare content domains, where are they going? And what keywords are they using? Using that data, we noticed some confusion between our newer Bulk Redirects feature and Forwarding Page Rules. Even though both features let you forward URLs – and Bulk Redirects is easier and more flexible – very few searches using “url forwarding” reached the Bulk Redirects page. To address that, we tweaked our keywords and added a section to our Forwarding Page Rules article breaking down the differences between the features.
Though internal and external searches tend to provide the most actionable data, we also look at broader trends in other metrics (pageviews, documentation maintenance cost, support tickets, and more). We can’t use these metrics to exactly “measure success”, because it’s hard to attribute any changes to the quality of our docs. For example, if there’s suddenly a spike in traffic to our DNS docs, does that mean that our docs are doing well? Or maybe we just blogged about a new feature? Or more customers might be onboarding their domains within a specific timeframe?
We can, however, use these metrics to broadly look at our relative effort across different products and adjust priorities accordingly. To use DNS as an example, it’s towards the top in terms of support tickets, but we actually have a comparatively small percentage of our content dedicated towards it. That means that, if we see more opportunities to improve those docs, those opportunities will likely get a higher priority.
Conclusion
When we take all these inputs together – the qualitative experience of dogfooding our documentation and our products, the broad outlines of our user-focused content journey, the community feedback from our open-source ecosystem, and the quantitative data points from our analytics – they help us treat our content as a product.
It’s part of what makes this team so fun to be a part of! Speaking of, we’re hiring!
