Categories
blogging documentation writing

Rotate your stock

As a university student, I worked one summer as a line cook in a new-age tempura restaurant. The chef there was a grizzled US Navy veteran who went by Lodi. He spoke with a New Hampshire accent and worked his knife like a man gutting fish on a trawler coming ’round the Portsmouth Harbor Lighthouse.

My first day on the job, he showed me the walk-in refrigerator, a cold, damp, vault with shelves from floor to ceiling. He said:

Upper and lower shelves are for produce boxes fresh off the truck.  Shelves from your head to your waist are for food that’s ready-to-cook or ready-to-serve.

Always put a lid on your containers and always rotate your stock. Everything should have an expiration date. Toss out everything that’s expired. Cut off anything that’s spoiled. Sniff or eyeball everything and ask yourself if you’d eat it. If in doubt, toss it out.

Then, bring the good stuff forward to make space behind it. Before the lunch rush and any time you’ve got a minute to spare, cut vegetables and prepare food to fill these empty spaces.

It seems like common sense now, but as a young man, this system made a big impression on me.

I’m still doing it in my work today. I just finished a project where I inspected my team’s entire doc repository, tossed out the obsolete, refreshed the good, and moved it forward.

You can do this, too. For tech docs or blog posts:

  • Inspect your legacy content at regular intervals.
  • Remove what’s obsolete.
  • Refresh what’s good and bring it forward.
  • Fill your customers’ information needs with new content.
  • Take steps to make the process more systematic.

In tech docs, there are ways to make replacing content easier:

  • Keep a release-cycle checklist with a “remove obsolete content” task on it.
  • Write modular documentation.
  • Tag content that’s version-specific so you can search for it.
  • Use link checking software.
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.

Categories
jobs learning technical writing

Do you need tech writing experience? Write for one of these open-source projects.

https://medium.com/@rolfedh/do-you-need-tech-writing-experience-write-for-one-of-these-open-source-projects-14aa84de827b