Why write docs like code

Docs-as-code means treating documentation as a first-class engineering artifact: write it with the same tools, versioning, and automated checks used for software. At Cloudflare, the approach extends to running the whole operation in the open. The cloudflare-docs GitHub repository is public, so external contributors can propose changes, report inaccuracies, and effectively surface bugs that would otherwise go unnoticed. Community pull requests have been particularly valuable for catching errors — not just in the documentation itself, but also in product behavior.

The toolchain behind Developer Docs

Cloudflare publishes product documentation through this docs-as-code pipeline. Changes live in Git, hosted in a public GitHub repository, which handles branching, merging, and change tracking. GitHub Actions and Cloudflare Pages provide the continuous integration and delivery (CI/CD): the pipeline verifies that the documentation builds successfully and checks for broken links on every change.

Each pull request generates a preview, so reviewers don't need to set up a local environment. For contributors who prefer a full build, the project also supports local development using open-source tooling.

This setup yields several practical benefits:

  • Familiar workflows. Engineers can review docs using the same Git-based processes they use for code.
  • Easy contribution. The same GitHub interface is approachable enough for non-technical colleagues and community members.
  • Fast iteration. Deploying an approved change is a single click; local builds are quick thanks to recent engine changes.
  • Safe restructuring. The CI/CD pipeline guarantees that reorganizing sections won't leave broken links behind.

Tooling alone doesn't ensure quality — the docs-as-code philosophy is what lets writers focus on producing clear, accurate, and navigable content rather than worrying about build failures or link rot.

Public by default

Running documentation in a private repository would still deliver the core benefits of docs-as-code. Cloudflare's decision to go public extends those benefits to outside collaborators. For every contribution — internal or external — the review process is the same: check that the content matches the style guide and content strategy, request technical validation when needed, and merge once approved.

Issues and pull requests from the community are treated like internal tickets. They get assigned, prioritized, and handled even though they may live in a separate backlog from internal work. When feedback isn't about documentation at all, every page includes a mechanism to route product feedback to the appropriate internal team.

Contributors who want to get involved should read the Contributing to Cloudflare's Documentation page in the public repository.

Handling non-public content

Not everything can ship in the open before launch. Teams handle pre-release content in a couple of ways, depending on the writer and stakeholders involved:

  • Work in a shared document for direct feedback, then create the Markdown version and push it to the public repository near the release date.
  • Use a private Git repository with the same docs-as-code processes. When it's time to go public, pushing the content is straightforward — move the branch to the public remote and open a pull request.

Toward more transparency

The documentation process is already largely public, but there's room for improvement. Cloudflare currently provides issue creation templates and pull request guidelines, and plans to publish its style guide and content strategy. Making those public would let contributors understand review criteria in advance, making the entire contribution process more predictable.