This post is also available in 简体中文 and 繁體中文.
Docs-as-code is an approach to writing and publishing documentation with the same tools and processes developers use to create code. This philosophy has become more popular in recent years, especially in tech companies. Automatic link checking is part of this process, which ensures that writer's changes are sound and safe to deploy. By setting the stage with a docs-as-code approach, technical writers can focus on what they do best: ensure that our readers get useful and accurate information that is easy to find, and our documentation speaks a single language.
Besides following a docs-as-code approach, at Cloudflare we handle our documentation changes in public, in our cloudflare-docs GitHub repository. Having our documentation open to external contributions has helped us improve our documentation over time — our community is great at finding issues! While we need to review these contributions and ensure that they fit our style guide and content strategy, the contributions provided by the Cloudflare community have been instrumental in making our documentation better every day. While Cloudflare helps build a better Internet, our community helps build better documentation.
Docs-as-code at Cloudflare
At Cloudflare, we follow a docs-as-code approach to create and publish product documentation in Developer Docs.
Such an approach involves different components. We use Git with a public GitHub repository to keep track of changes and to handle branching and merging. We rely on GitHub Actions and Cloudflare Pages for continuous integration and delivery (CI/CD). Our continuous integration pipeline checks if the documentation builds successfully and if there are any broken links. Users, both internal and external, can preview the changes in each pull request, which means that collaborators don't have to set up local environments to preview the changes they're proposing. However, if they wish to do so, users can set up a local environment using open-source tools and create local builds of the documentation.
Following this docs-as-code strategy has a few advantages. We use well-known workflows that technical folks use on a daily basis. This makes it easier to get feedback from engineers, while still being simple enough to get contributions from less tech-inclined people in the company and from the general Cloudflare community. After reviewing and approving a contribution to the documentation, we can deploy those changes to the live documentation site with the click of a button. Thanks to recent changes in our documentation engine, both deployments and local builds are fast, which helps increase our team's velocity. Additionally, it's safe to restructure parts of the documentation without being afraid of breaking stuff — our CI/CD pipeline ensures we don't have broken links.
Our open source approach
It's possible to use a docs-as-code approach internally, using private repositories. However, we would not be extending some benefits of this approach to contributions provided by the larger Cloudflare community.
As a technical writer at Cloudflare, the great part about documentation-related work is that it’s done in our public GitHub repository. I can push changes to the cloudflare-docs GitHub repository with new or updated documentation that is then reviewed by my Cloudflare stakeholders, such as product managers and engineers.
Besides this work done together with other Cloudflare employees, I can also address issues and review pull requests from external stakeholders, since our documentation is open source. For example, pull request #4601 from an external contributor fixed an expression that was incorrect in the documentation:
Thanks to these contributions, we have been able to identify many issues, not just in the documentation but also in our products!
We handle these contributions as part of maintaining our own documentation product, with its own bugs and feature requests. Issues and pull requests get assigned, prioritized, handled, and reviewed just like internal tickets – even though they're not all in the same backlog.
Our work is similar both for internal and external contributions. We review the proposed changes, making sure that the new or updated content follows our style guide and our content strategy. When required, we ask for technical validation of the content. Finally, we merge the changes when they're approved.
For issues that are not related to the documentation, we have a feedback mechanism in every documentation page that allows readers to provide feedback about the product itself. This information is then reviewed internally and addressed by the correct team.
For more information on how you can contribute to the documentation by creating an issue or a pull request, refer to the Contributing to Cloudflare's Documentation page in our public GitHub repository.
Keeping some secrets
For content that we cannot disclose just yet, we currently have several approaches, depending on the exact technical writer and on the involved stakeholders.
In some situations, we work on a shared document where we receive and address direct feedback. Close to the feature release date, we create the corresponding Markdown version that we push to the public GitHub repository at the right time.
In other cases, we work in a private Git repository, getting early feedback using the same processes we have in place for our public repository. This method of handling non-public content is easy to implement because we're already following a docs-as-code approach. In this case, pushing the content to GitHub is a straightforward operation when the time comes — it's just a matter of pushing the branch to a different remote and creating a public pull request.
What's next
Much of our work is already done in public, but we can still improve. While we do provide issue creation templates and pull request guidelines, we'll eventually make our style guide and content strategy public. This will allow users to know in advance what we will check for (and enforce) for every contribution to the public documentation, making our review process more transparent.