BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage News Cloudflare Open Sources Documentation and Adopts Astro for Better Scalability

Cloudflare Open Sources Documentation and Adopts Astro for Better Scalability

Cloudflare recently published an article detailing their upgrade of developer documentation by migrating from Hugo to the Astro ecosystem. All Cloudflare documentation is open source on GitHub, with opportunities for community contributions.

The developers.cloudflare.com site was previously consolidated from a collection of Workers Sites into a single Cloudflare Pages instance. The process used tools like Hugo and Gatsby to convert thousands of Markdown pages into HTML, CSS, and JavaScript. Kim Jeske, head of product content at Cloudflare, Kian Newman-Hazel, document platform engineer at Cloudflare, and Kody Jackson, technical writing manager at Cloudflare, explain the reasons behind the change in the web framework:

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.

In 2021, Cloudflare adopted a "content like a product" strategy, emphasizing the need for world-class content that anticipates user needs and supports the creation of accessible products. Jeske, Newman-Hazel, and Jackson write:

Open source documentation empowers the developer community because it allows anyone, anywhere, to contribute content. By making both the content and the framework of the documentation site publicly accessible, we provide developers with the opportunity to not only improve the material itself but also understand and engage with the processes that govern how the documentation is built, approved, and maintained.

According to the team, Astro's documentation theme, Starlight, was a key factor in the decision to migrate the documentation site: the theme offers powerful component overrides and a plugin system to utilize built-in components and base styling. Jeremy Daly, director of research at CloudZero, comments:

Cloudflare has open sourced all their developer documentation and migrated from Hugo to the Astro, with the JavaScript ecosystem claiming another victim. No matter how good your documentation is, user feedback is essential to keeping it up-to-date and accessible to all.

According to the Cloudflare team, keeping all documentation open source allows the company to stay connected with the community and quickly implement feedback, a strategy not commonly shared by other hyperscalers. As previously reported on InfoQ, AWS shifted its approach after maintaining most of its documentation as open source for five years. In 2023, the cloud provider retired all public GitHub documentation, citing the challenge of keeping it aligned with internal versions and the manual effort required to sync with GitHub repositories. Jeff Barr, chief evangelist at AWS, wrote at the time:

The overhead was very high and actually consumed precious time that could have been put to use in ways that more directly improved the quality of the documentation.

Gianluca Arbezzano, software engineer at Mathi, highlights the significance of the topic:

If you are thinking: "it is just documentation", I think you should care a bit more! We deserve only the best! Nice article from Cloudflare about their migration from Hugo to Astro.

Commenting on the Cloudflare article on Hacker News, Alex Hovhannisyan cautions:

I'm sorry but I have to be honest as someone who recently migrated from Netlify (and is considering moving back): the documentation is not very good, and your tech stack has nothing to do with it. End users don't care what tech stack you use for your docs.

All Cloudflare documentation is available at developers.cloudflare.com.

About the Author

Rate this Article

Adoption
Style

BT