However, we would not be extending some benefits of this approach to contributions provided by the larger Cloudflare community.Īs a technical writer at Cloudflare, the great part about documentation-related work is that it’s done in our public GitHub repository. It’s possible to use a docs-as-code approach internally, using private repositories. 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. Thanks to recent changes in our documentation engine, both deployments and local builds are fast, which helps increase our team’s velocity. 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. 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. We use well-known workflows that technical folks use on a daily basis. 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.įollowing this docs-as-code strategy has a few advantages. 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.
Our continuous integration pipeline checks if the documentation builds successfully and if there are any broken links. We rely on GitHub Actions and Cloudflare Pages for continuous integration and delivery (CI/CD). We use Git with a public GitHub repository to keep track of changes and to handle branching and merging. Such an approach involves different components. Docs-as-code at CloudflareĪt Cloudflare, we follow a docs-as-code approach to create and publish product documentation in Developer Docs. While Cloudflare helps build a better Internet, our community helps build better documentation. 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. 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.īesides following a docs-as-code approach, at Cloudflare we handle our documentation changes in public, in our cloudflare-docs GitHub repository.
Automatic link checking is part of this process, which ensures that writer’s changes are sound and safe to deploy. This philosophy has become more popular in recent years, especially in tech companies. Docs-as-code is an approach to writing and publishing documentation with the same tools and processes developers use to create code.
0 kommentar(er)
