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.

Developer-contributed content in upstream docs

“No software spec survives first contact with the compiler.”

One of the interesting bits in the project type #1: Team=Both, Code=Up>Down, Docs=Down>Up scenario is when developers write up their feature plans in the upstream repo. Often, these show up in the /doc subdirectory.

  • Often, before coding, a developer writes up a description of the new feature they plan to code. They use this document to discuss and negotiate its implementation with other team members.
  • When the developer starts coding, code reviews replace the document as the forum of discussion.
  • Reading these feature plans and related discussions is like seeing an artist’s preliminary sketches: They represent the intention more than the result.
  • Sometimes, these preliminary docs reflect the developer’s concerns more than users’ and customers’ needs. They focus on back-end issues, celebrate accomplishments, and explain decisions.
  • These topics tend to focus more on the feature than the user story.
  • Toward the end of the project, as the feature approaches release, the developer might add user instructions to these documents.
  • Sometimes these plans describe features that didn’t make it into the software, made it in as beta or tech-preview features, or describe features that have been superseded.

In a future post, I’ll write about how to analyze and use these upstream docs to create better customer-facing docs.

Writing and publishing on GitHub

I hope to create an open community around documenting open-source software and practice what I preach: To eat my dog food, as they say. What better way than to create a repo and invite the contributions of other writers?

To be honest, its a bit tough to do this. I believe in “open source.” I promote it, even.

But here I am preparing to put my most ambitious project out there for others to join, and part of me is holding back. Inviting others to join challenges my sense of ownership. To put these feelings in words: Will this end up creating a mess of written-by-committee pablum that serves little purpose? As a writer, I like to revise and craft my work iteratively. How can I do that if I’m fending off the well-intentioned interference of other writers looking over my shoulder?

To overcome this hesitation, I have to re-envision my notions of ownership. Is this “my content?” Is this “my project?” Aside from contributing content, then, I hope to provide the system by which it gets created.

Systems are composed of people, processes, and technology.

This system I’m creating will consist of: