Great documentation empowers users to be successful with a new product as quickly as possible, showing them how to use the product and describing its benefits. Relevant, timely, and accurate content can save frustration, time, and money. Open source documentation adds a few more benefits, including building inclusive and supportive communities that help reduce the learning curve. We love being open source!

While the Cloudflare content team has scaled to deliver documentation alongside product launches, the open source documentation site itself was not scaling well. developers.cloudflare.com had outgrown the workflow for contributors, plus we were missing out on all the neat stuff created by developers in the community.

Just like a software product evaluation, we reviewed our business needs. We asked ourselves if remaining open source was appropriate? Were there other tools we wanted to use? What benefits did we want to see in a year or in five years? Our biggest limitations in addition to the contributor workflow challenges seemed to be around scalability and high maintenance costs for user experience improvements. 

After compiling our wishlist of new features to implement, we reaffirmed our commitment to open source. We valued the benefit of open source in both the content and the underlying framework of our documentation site. This commitment goes beyond technical considerations, because it's a fundamental aspect of our relationship with our community and our philosophy of transparency and collaboration. While the choice of an open source framework to build the site on might not be visible to many visitors, we recognized its significance for our community of developers and contributors. Our decision-making process was heavily influenced by two primary factors: first, whether the update would enhance the collaborative ecosystem, and second, how it would improve the overall documentation experience. This focus reflects that our open source principles, applied to both content and infrastructure, are essential for fostering innovation, ensuring quality through peer review, and building a more engaged and empowered user community.

Cloudflare’s developer documentation is open source on GitHub, with content supporting all of Cloudflare’s products. The underlying documentation engine has gone through a few iterations, with the first version of the site released in 2020. That first version provided dev-friendly features such as dark mode and proper code syntax. 

In 2021, we introduced a new custom documentation engine, bringing significant improvements to the Cloudflare content experience. The benefits of the Gatsby to Hugo migration included:

• Faster development flow: The development flow replicated production behavior, increasing iteration speed and confidence. Preview links via Cloudflare Pages were also introduced, so the content team and stakeholders could quickly review what content would look like in production.

• Custom components: Introduced features like resources-by-selector which let us reference content throughout the repository and gave us the flexibility to expand checks and automations.

• Structured changelog management: Implementation of structured YAML changelog entries which facilitated sharing with various platforms like RSS feeds, Developer Discord, and within the docs themselves.

• Improved performance: Significant page load time improvements with the migration to HTML-first and almost instantaneous local builds.

These features were non-negotiable as part of our evaluation of whether to migrate. We knew that any update to the site had to maintain the functionality we’d established as core parts of the new experience.

After careful evaluation, we chose to migrate from Hugo to the Astro (and by extension, JavaScript) ecosystem. Astro fulfilled many items on our wishlist including:

• Enhanced content organization: Improved tagging and better cross-referencing of  related pages.

• Extensibility: Support for user plugins like starlight-image-zoom for lightbox functionality.

• Development experience: Type-checking at build time with astro check, along with syntax highlighting, Intellisense, diagnostic messages, and plugins for ESLint, Stylelint, and Prettier. 

• JavaScript/TypeScript support: Aligned the docs site framework with the preferred languages of many contributors, facilitating easier contribution.

• CSS management: Introduction of Tailwind and scoped styles.

• Content collections: Offered various ways to manage and enhance tagging practices including Markdown front matter validated by Zod schemas, JSON schemas for Intellisense, and a JavaScript callback for filtering returned entries.

Starlight, Astro’s documentation theme, was a key factor in the decision. Its powerful component overrides and plugins system allowed us to leverage built-in components and base styling.

Content needed to be migrated quickly. With dozens of pull requests opened and merged each day, entering a code freeze for a week simply wasn’t feasible. This is where the nature of abstract syntax trees (ASTs) came into play, only parsing the structure of a Markdown document rather than details like whitespace or indentation that would make a regular expression approach tricky.

With Hugo in 2021, we configured code block functionality like titles or line highlights with front matter inside the code block.

---
title: index.js
highlight: 1
---
const foo = "bar";

Starlight uses Expressive Code for code blocks, and these options are now on the opening code fence.

js title="index.js" {1}
const foo = "bar";

With astray, this is a simple as visiting the `code` nodes and:

1. Parsing `node.value` with front-matter.

2. Assigning the attributes from `front-matter` to `node.meta`.

3. Replacing `node.value` with the rest of the code block.

import { fromMarkdown } from "mdast-util-from-markdown";
import { toMarkdown } from "mdast-util-to-markdown";
 
import * as astray from "astray";
import type * as MDAST from "mdast";
import fm from "front-matter";
 
const markdown = await Bun.file("example.md").text();
 
const AST = fromMarkdown(markdown);
 
astray.walk<MDAST.Root, void, any>(AST, {
    code(node: MDAST.Code) {
        const { attributes, body } = fm(node.value);
        const { title, highlight } = attributes;
 
        if (title) {
            node.meta = `title="${title}"`;
        }
 
        if (highlight) {
            node.meta += ` {${highlight}}`;
        }
 
        node.value = body;
 
        return;
    }
})

When we migrated from Gatsby to Hugo in 2021, the pull request included 4,850 files and the migration took close to three weeks from planning to implementation. This time around, the migration was nearly twice as large, with 8,060 files changed. Our planning and migration took six weeks in total:

• 10 days: Evaluate platforms, vendors, and features 

• 14 days: Migrate the components required by the documentation site

• 5 days: Staging and user acceptance testing (UAT) 

• 8 hours: Code freeze and migrate to Astro/Starlight

The migration resulted in removing a net -19,624 lines of code from our maintenance burden.

While the number of files had grown substantially since our last major migration, our strategy was very similar to the 2021 migration. We used Markdown AST and astray, a utility to walk ASTs, created specifically for the previous migration!

A website migration like our move to Astro/Starlight is a complex process that requires time to plan, review, and coordinate, and our preparation paid off! Including our Cloudflare Community MVPs as part of the planning and review period proved incredibly helpful. They provided great guidance and feedback as we planned for the migration. We only needed one day of code freeze, and there were no rollbacks or major incidents. Visitors to the site never experienced downtime, and overall the migration was a major success.

During testing, we ran into several use cases that warranted using experimental Astro APIs. These APIs were always well documented, thanks to fantastic open source content from the Astro community. We were able to implement them quickly without impacting our release timeline.

We also ran into an edge case with build time performance due to the number of pages on our site (4000+). The Astro team was quick to triage the problem and begin investigation for a permanent fix. Their fast, helpful fixes made us truly grateful for the support from the Astro Discord server. A big thank you to the Astro/Starlight community!

Migrating developers.cloudflare.com to Astro/Starlight is just one example of the ways we prioritize world-class documentation and user experiences at Cloudflare. Our deep investment in documentation makes this a great place to work for technical writers, UX strategists, and many other content creators. Since adopting a content like a product strategy in 2021, we have evolved to better serve the open source community by focusing on inclusivity and transparency, which ultimately leads to happier Cloudflare users. 

We invite everyone to connect with us and explore these exciting new updates. Feel free to reach out if you’d like to speak with someone on the content team or share feedback about our documentation. You can share your thoughts or submit a pull request directly on the cloudflare-docs repository in GitHub.

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.

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.

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.

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!

...We protect entire corporate networks, help customers build Internet-scale applications efficiently, accelerate any website or Internet application, ward off DDoS attacks, keep hackers at bay, and can help you on your journey to Zero Trust.

Visit 1.1.1.1 from any device to get started with our free app that makes your Internet faster and safer.To learn more about our mission to help build a better Internet, start here. If you’re looking for a new career direction, check out our open positions.