Categories
open source technical writing

Well begun (in Git) is half done

Well begun is half done.

~ Aristotle

Inspired by James Clear’s book, Atomic Habits, I’ve started starting tasks before it’s time to do them.

For example, I prepare the Keurig coffee machine before bed each night. I fill the reusable filter with fresh coffee grounds and top up the reservoir with water. As a sign that everything is ready, I put a cup upside down under the spout.

Eight hours later, in the half-dark of the morning, I flip the cup, push two buttons, and out comes the coffee. No fumbling, running the tap or clinking the cups in the kitchen while other folks and dogs are still asleep. Just flip cup+power on+press start. Voila! Coffee made.

Lately, I’ve been applying this practice to my work using git.

Recently, I documented a new product feature. As we approached the release date, we ran into a software problem we could not fix in time. Instead, I documented a workaround for users to complete before they use the new feature.

The workaround consists of an asciidoc assembly file and a handful of module files. To make sure users notice the workaround, I added a couple of cross-references to other topics. I followed the normal process of git pushing these changes to the doc repo (i.e., creating a pull request and having the changes reviewed, merged, and published).

Soon, the team will fix the problem. When we release the software patch, I need to remove the workaround from our docs.

Here’s the part about using git to get well begun. An hour or so after I published the workaround, with the file names and cross-references still fresh in my memory, I did my future work ahead of time:

  • Created a working branch in git.
  • Deleted the workaround files and cross-references
  • Squashed and pushed the commit.
  • Created a pull request (PR).
  • Put the PR out for review by the team (no changes required).

This pull request means that on the day the software patch is ready, I only need a few minutes to rebase, fix conflicts (none so far), and merge. Voila! Change published.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.