CI-CD - What is it and why technical writers need to know about it?

Continuous Integration-Continuous Delivery (Ravi and Bharat are away for Visarjan this week - so we could not involve them in this post)

What is CI-CD?

It's easier to explain what it is not. Earlier, this is what happened in non CI and non CD:

• Integration: Two developers would sit in a room and manually merge their code changes. Sometimes this would go smoothly, but other times it would lead to merge conflicts that would take hours or even days to resolve.
• Deployment: Once the code was integrated, it would be deployed to production by a team of engineers. This typically involved manually copying and pasting the code onto the production servers, then restarting the servers. This was a risky process, and there were always concerns that something would go wrong and the production environment would be brought down.

Now, none of this happens. With CI-CD, a yaml file with instructions uses automation tools such as Jenkins, Maven, and Gradle to do all of the above automatically.

How a DevOps guy (the creator of builds) will explain it?

So builds are automatically created as soon as the (small changes in) code is checked in and changes are pushed live (well almost immediately). There may be steps for manual review and approval involved before that live push (hopefully).

What does it look like?

For example, the following yaml (yes, YAML does this too) - sits in the root of a Git repo. This CI/CD pipeline automates the build, test, and deployment of a Python web app. It builds a container image of the web app and pushes it to Docker Hub. (See comments in the code for detail of the steps - and think how relevant these are potentially for the doc build process)

# This YAML file defines a CI/CD pipeline for a Python web application using GitHub Actions.

name: CI/CD Pipeline

# The pipeline is triggered whenever a change is pushed to the `main` branch of the repository.
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    # This step checks out the code from the Git repository.
    steps:
      - uses: actions/checkout@v3

      # This step sets up a Python environment.
      - name: Set up Python
        uses: actions/setup-python@v3
        with:
          python-version: 3.10

      # This step installs the Python dependencies for the web application.
      - name: Install dependencies
        run: pip install -r requirements.txt

      # This step runs the unit tests for the web application.
      - name: Run tests
        run: pytest

      # This step builds a container image of the web application.
      - name: Build container image
        run: docker build -t my-app .

      # This step pushes the container image to Docker Hub.
      - name: Push container image to Docker Hub
        run: docker push my-app
        

Why should Technical Writers know (worry) about CI-CD?

Cause documentation is nothing but a build of a software, technically. And even more so in Docs-as-Code paradigm, code and docs are inseparable.

The pipeline already has the docs

Docs too are increasingly being served through a CI-CD pipeline. And the same reflects in the following survey on linkedin:

https://www.dhirubhai.net/feed/update/urn:li:activity:7112370065307578368/

The pipeline can help us technical writers

The first couple of things that come to my mind are that CI-CD can help the doc teams keep the docs current and more accurate:

• Example 1: The process to run checks on image formats, broken links, etc can be triggered as soon as new content is checked in.
• Example 2: A doc issue can be created in JIRA automatically on a REST API Change and the Swagger spec can be updated on the server as soon as a change is approved. This will ensure nothing is missed.

What's different for the Technical Writers?

You check in and it's live. Be ready for it.

And you won't be seeing screens like this anymore (yea - a build creation screen):

How much of tech do the technical writers need to absorb for CI CD?

Not too much - we just need to be thorough with our Git and the CI CD process and understand that there's shorter turnaround time. Technical Writers need not build anything but just need to understand how the new paradigm works.

With better understanding, we will be able to get the DevOps device processes and tech for the technical documentation that will improve our productivity and accuracy.

Does your doc team work with CI CD? How do you utilize it? Please comment.