Make writing documentation part of your pull request

We are all guilty of this one! We changed something, and we forgot to update the documentation. Even if you have the best intentions to do your best, it’s way too easy not to do it.

Why is it so easy to skip?

Assume you changed something, created a pull request, and followed all the defined processes before you can merge the change. When is the best time to update the documentation in this process? If you update the documentation while the pull request is open, the documentation is ahead. It refers to a state that might not be true until you merge your pull request. What if you decide not to merge? Will you remember to revert the documentation?

The other way around is also far from ideal. Before you are ready to merge the pull request, it might take some iterations. Your peers give feedback and comments. So, by the time you have your pull request ready to be merged, you are already mentally done with it. So you need discipline to do the extra step and write the documentation.

Of course, you can make this part of a definition of done and create all sorts of processes around it. But these highly rely on the professionalism of the team itself.

Make it part of your pull request.

I began my career as a software engineer, where I learned concepts like encapsulation. The idea is simple: You place all the things that belong to each other as close as possible.

Let’s apply this concept to the documentation of our solution. We can place the documentation in our git repository and change the logic and behavior in a pull request. The developer can also include any documentation changes in this same pull request. For the reviewer, it becomes easier. They see the code changes and the documentation changes, and they can see the correlation between them. When a developer forgets to update the documentation, peers can ask for the documentation changes as well. So, it’s a win-win situation already!

But my audience does not use git!

Most companies that I worked for use Confluence for their documentation. However, this does not have to stop you from using git! You can sync your Markdown-based documentation to Confluence using mark!

In this example, I use the GitHub actions to perform the sync action when we push to our main branch:

name: Deploy the documentation to confluence
on:
  push:
    branches:
      - main
jobs:
  Documentation:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Setup Golang
        uses: actions/setup-go@v5
        with:
          go-version: '^1.21.13'
          cache-dependency-path: "**/go.sum"
      - name: Install dependencies
        run: go install github.com/kovetskiy/mark@latest
      - name: Sync Documentation
        env:
          MARK_SPACE: MySpace
          MARK_BASE_URL: https://xebia.atlassian.net/wiki
          MARK_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
          MARK_PASSWORD: ${{ secrets.CONFLUENCE_PASSWORD }}
        run: |
          MESSAGE=$(git log -1 --pretty=format:"%s (by %an in %h)")
          UPDATED_DOC_FILES=$(git diff-tree --no-commit-id --name-only -r HEAD --root docs | grep '\.md$' || true)
          for FILE in ${UPDATED_DOC_FILES}; do
            if [[ -e "${FILE}" ]]; then
              echo "> Sync ${FILE}";
              mark --version-message="${MESSAGE}" --drop-h1 --title-from-h1 -f ${FILE} || exit 1; echo;
            else
              echo "> Skipping ${FILE} as it was deleted in the last commit";
            fi
          done

Let’s break it down into smaller steps:

• Check out the code with a depth of 2. This enables us to detect the changes made in the last commit.
• Ensure we have a Golang environment, and we will cache the dependencies to speed up the build process.
• Installing mark into the environment.
• Grab the last commit message.
• Grab Markdown files from the last commit that have been updated.
• Sync each file that has been changed, use the commit message in the confluence version management.

Pretty cool, right? Now, when the pull request is merged, the changes made, including the documentation, are applied when they are merged! Unfortunately, this tool does not support deleting pages.

Conclusion

By combining the documentation with your code, you will encapsulate them. This will make it easier to keep them up to date and thus improve the overall quality.

Photo by Pixabay