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.

Categories
open source technical writing

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.

Categories
open source technical writing

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:

Categories
open source technical writing

My Story

A few days ago, I was looking at Red Hat Summit 2020 and was surprised (well…not very surprised) there were no sessions dedicated to documenting open-source software.

Most open-source projects need documentation, or at least better documentation. Voila! Opportunity strikes. If I put together enough material, maybe I can help someone solve that problem. If my solutions have value, maybe I’ll get an opportunity to present at Summit or All Things Open in Raleigh next year.

So, on a whim and a prayer, I’ve set out to produce the most stupendous compendium of information ever amassed on the topic: documenting open-source software

But where to start?

Thirty years ago my older brother, who was ten years old at the time, was trying to get a report written on birds that he’d had three months to write, which was due the next day. We were out at our family cabin in Bolinas, and he was at the kitchen table close to tears, surrounded by binder paper and pencils and unopened books about birds, immobilized by the hugeness of the task ahead. Then my father sat down beside him put his arm around my brother’s shoulder, and said, “Bird by bird, buddy. Just take it bird by bird.

― Anne Lamott, Bird by Bird: Some Instructions on Writing and Life

So, which are my first birds?

I’ll start by writing about topics that are relevant to my work right now.