CI/CD and Docs-as-Code workflow

What is CI/CD development? How does it relate to docs-as-code? How can I write and maintain human-readable documentation while incorporating automated tools to my review process? We provide an infographic and a description that illustrates our take on how CI/CD documentation, DocOps, and the docs-as-code integrate.

What is CI/CD development?

CI/CD stands for Continuous Integration and Continuous Delivery or Deployment. The main goal of the CI/CD approach is to reduce the repetitive part of the work of software developers using automation tools and testing environments for the sake of collaboration, efficiency and productivity. With a reliable CI/CD framework developers can deliver new product releases in a short time (continuously). We can speak of Continuous Deployment when every change in the code automatically and immediately becomes a part of the product being made.

CI/CD workflow example

Git and the workflows that came from it allow developers to work in parallel to write, test, build, test, and deploy without waiting for everyone to be done.

Take for example Developer Kitten who’s working on a new product feature simultaneously with other developers in her team. She uses an Integrated Development Environment (IDE) that consists of a source code editor and an automated testing framework (validators, syntax checkers - some refer to them as “linters” -, or code beautifiers).

1. Developer Kitten pulls the current state of a working repository where the code of the main product is stored using a version control system (Git, Gerrit, Bitbucket).
2. When she’s finished coding, she creates a change request and pushes the changes (commits) into the version control system for a review. Here some automatic validators can run to detect possible syntax violations. If the reviewers and/or the automatic validator spot errors or merge conflicts, Developer Kitten has to amend her change requests.
3. Once the code passes testing, it is merged to the repository and can be deployed right in the next release. Product Owner Bunny is happy because she can be sure that the company can ship the new version of the product in time without functional errors.

How can the CI/CD process be applied to documentation writing? The docs-as-code approach is a prerequisite for implementing a CI/CD documentation method.

What is docs-as-code

You need to create content that engages and informs your audience and to share the values of your company and your product. Consistent documentation that is up to date and free from errors (just like an application without bugs) is essential for achieving this. 

The docs-as-code (or sometimes docs-like-code) approach means that you create and maintain your documentation just as rigorously as you do your programming code. The technical writers can be members of the agile teams, so they work in sprints, and they use the same (or similar) IDEs and workflows as developers. 

The part where people often trip up is in the implementation of docs-as-code where they try to use a singular test framework for checking both code and documentation. However they can have two separate test frameworks: linters and other validators for human-readable documentation and a separate automated test framework for checking code. There is some benefit to keeping human-readable documentation in a separate but parallel file to the source code (still within the same file structure). Alternatively, a means of differentiating between the two types of text needs to be devised and given to the test framework so that relevant results can be generated. Depending on your use case, either or both standards may be applicable. For example, documentation generated by developers within the code may be upheld to one standard whereas documentation generated by technical writers would adhere to another.

Five goals of docs-as-code:

• Outlining and polishing a content strategy
• Adhere and improve the editorial style guide
• Applying and developing tools for automated testing
• Applying and developing tools for automated deployment
• Utilizing analytics, statistics, and customer feedback

CI/CD documentation by example

Techwriter Puppy is working on a new product feature documentation in whatever-flavoured markdown. He, like his colleague Developer Kitten, uses an IDE toolkit that consists of a plain text editor (it can be the same source code editor that Kitten uses) and linters to keep the documentation consistent and to find style guide- and syntax violations, broken links, typos, missing or unused assets.

1. Techwriter Puppy pulls the current state of a working repository where the documentation is stored using a version control system (Git, Gerrit, Bitbucket).
2. When he’s finished writing, he creates a change request and pushes the documentation (commits) into the version control system for review. Here some automatic validators can run to detect possible functional errors that he may have left in the text. If Product Owner Bunny and members of the Documentation Review Team or the automatic validator spot errors or a merge conflict, Techwriter Puppy has to amend his change request.
3. Once the documentation passes testing, it is being merged to the repository, and can be published to the documentation site or developer portal right away, or can be shipped with the next product release (because up-to-date documentation is part of your Definition of Done). Product Owner Bunny is happy because she can be sure that the new version of the documentation is free of functional errors, and is able to address its audience in a tone that mirrors the values of the company.

Is docs-as-code beneficial for you?

When testing frameworks were first introduced to developers, there was a considerable backlash because now rather than fixing a bug on the fly, they were made to follow a process that seemed cumbersome. As testing frameworks became the norm, developers started to embrace the practice because it helps them look good. Code failing due to a missing parenthesis or illogical word choice started to become a thing of the past. Developers could now focus on writing the code needed to fix the problem knowing that like a spell checker or grammar checker in word, the test framework would catch their occasional slip-up and result in an immediate fail prior to any of their code touching production. 

In this same way, we are encountering a push back to docs-as-code in the documentation life cycle. Writers feel this may be unreasonable because they must now go through a whole editorial process just to fix a typo in the text. A company may need an extravagant solution because they have an extremely complex documentation structure. Documentation that needs to be standardized may be stored right next to the code, embedded in the code, or in the commit messages. To implement a testing framework that will be successful requires initiative by the oversight documentation team or product owner to change existing practices and requires adoption from people across many teams.

How to start with docs-as-code

Docs-as-code as a tool is only useful in context

To build a sandcastle: the tools you use will reflect your taste and your needs. For example a bucket, a spade, some shapes, and a trowel. The attributes of the tools affect the result but don’t define it. In the same way, docs-as-code should not be what defines the final documentation. The automated test framework can replace the need for shapes but you will still need the bucket & spade: technical writer, reviewers, and trowel/product owner to work the documentation to its final product.

Docs-as-code does not replace the review process. It is useful as long as it helps to reduce the repetitive part of the work. 

Having resident linters in his local editorial environment helps Techwriter Puppy to find errors and more apt words during writing. He still has the autonomy to decide which linter suggestions he accepts or ignores.

Related Reading

If we piqued your interest and you would like to read more about CI/CD documentation, docs-as-code, automated checks, and analytics, here are some helpful links.