One of the key pillars of docs-as-code is releasing changes via CI/CD. Just as how software is often released continuously, we can keep our documentation up to date as the product changes.
This lets us achieve continuous documentation: instead of large bulk releases, we can incrementally improve our documentation, as we make changes to our product.
Let's dive into how continuous documentation is implemented in practice.
Making it easy to make changes
The key to continuous documentation is making it easy to contribute to documentation.
We want to lower the barrier to making changes, and empower contributors to make the docs better. Let's see how!
Smaller, iterative changes
The bigger the change, the harder it is to make. Everyone who has worked in the technology industry has seen large project spiral out of control, missing deadlines, and seemingly never ending.
Fast-moving teams get around this problem by splitting work into smaller chunks. Instead of a large monolithic release, preferring smaller, iterative changes that are easier to manage. Small changes are easier to review, have less risk, and can be shipped with fewer checks in place.
Releasing docs with code
It makes sense to update your product and documentation at the same time. Documentation should be in your "definition of done": a hard requirement for a feature to be released.
A Git monorepo, it's natural to even have code and documentation changes in the same branch or pull-request. Engineers and technical writers can work in the same branch, and eventually merge and deploy the code and documentation in tandem.
This is what we do at Doctave. We use a monorepo with a dedicated /docs folder. Every customer-facing feature will have documentation changes included, and get reviewed as part of the same pull-request on GitHub.
A multi-repository setup requires some more coordination. but the same principles apply. Every feature change should have a corresponding change in the documentation repository.
Empowering contributors
Documentation is the responsibility of the whole product team. We want to foster a culture where everyone is welcome to contribute by either writing or reviewing documentation.
Companies like Google, Twitter, and Spotify put a lot of effort into building a culture of documentation. We also see this at many of our customers: reviews are done not just by technical writers, but engineers and product managers responsible for the implementation of a feature.
Automate, automate, automate
Automation means your process is repeatable and, most importantly, transparent. You don't want to be bottlenecked by that one person who knows how to copy your final artifacts to the production server.
Instead, when changes are merged, they should automatically be deployed without human intervention.
If you are worried about quality issues, you can catch lots of common issues with tools like linters like Vale. They will check your content for spelling issues or unwanted phrases. This lessens some of the burden on the manual reviewer.
Implementing continuous documentation
Let's talk tactically: how do we implement continuous documentation in practice?
CI/CD integration
CI/CD plays an important part in continuous documentation since it's the engine automating everything.
The exact way you should implement CI/CD depends on your repository setup and choice of tools. At minimum, you need to be triggering automatic deployments whenever new changes are merged in your main branch.
To give a more complex example, we have an example in our documentation about how to integrate Doctave to your CI/CD pipeline in GitHub Actions.
The way it works is:
- Any time there is a pull request, or we've merged changes into the
mainbranch, - Check if there are changes to the
docs/subfolder, - If so, send the docs to Doctave
We then have versioning rules set up in Doctave that update the public-facing documentation when the main branch is updated. Else, we just get an isolated preview environment that we can use in our review process.
It's simple, and works great!
Building a culture of documentation
We want to empower contributors by building a culture of documentation. Instead of technical writers being solely responsible for docs, developers should feel welcome to write documentation for the features they are working on, and product managers should be considering how documentation fits into the overall product.
We have found there are three key steps to doing this:
- Standardize your process and tools: Teach everyone in your team how your documentation is updated
- Make documentation an expectation: No feature is done without great documentation
- Remove as much friction as possible: Have a development environment that Just Works™ and use the same workflows you're already using for reviewing code
Versioning and branching
It's important your team has an agreed upon strategy for versioning and branching documentation. We've written a whole article on versioning documentation, so we'll focus on branching strategies briefly in this section.
Choosing the right branching structure depends on your repository layout and team preferences. The goal is to ensure it's clear which documentation changes are associated with a specific product change.
As mentioned above, in the multi-repo case the docs changes may be in the same pull-request. In the multi-repo case, there may be branches in different repositories with matching names.
Having your team is aligned on your branching strategy makes releasing changes much more fluid and removes confusion.
Conclusions
Continuous documentation is not just a practice, but a mindset shift in how we approach documentation.
Here are the main takeaways:
- Embrace small, iterative changes
Continuous documentation thrives on the principle of making small, manageable updates to documentation.
- Foster a culture of documentation
By empowering all team members, from engineers to product managers, to contribute to documentation, we create a culture where documentation is everyone's responsibility.
- Leverage automation and CI/CD integration
Integrating documentation processes into CI/CD pipelines streamlines updates, making documentation an integral part of the development workflow.
Top comments (0)