My first (awful) video presentation

gently up the stream
Paddling upstream with a paddle

Ughh! 8 days for 8 minutes of awful video

A few weeks back, I saw an opportunity to give a presentation to my fellow developers. The dev lead for oVirt put out an RFP for the upcoming oVirt 2020 Online Conference.

Oh, and by the way, please prerecord your presentation so we can upload it to the conference YouTube channel.

Sure! I thought. No problem, I thought. I’ve given many live presentations, recording a video of one should be easy, I thought.

After a week of working on the material, a day of recording, and several hours of editing, the rendered video was eight, almost nine minutes long.

There I was, with a shaky voice, stumbling through my slides like I was in an elementary school play. Numerous jump cuts removed less successful takes.

A week of working on the material

My inspired brain-fart was to simplify modular documentation (aka “mod docs”) and provide a set of markdown templates. The purpose of doing this is to make mod docs easier for developers and other upstream contributors. My goal is to fix the problem of documentarians unintentionally driving away upstream contributors by bringing our specialized doc tools (asciidoc) and methods (mod docs) into upstream open-source projects.

The week flew quickly by as I tried to bring subtractive design to mod docs. I kept going off on tangents, developing a cute bento box analogy for mod docs (that I haven’t given up on yet). Every time I sat down to eat the frog, I wandered off to snack on the appetizers and side dishes instead. I had to work through the material, but that always takes more time than you think. In the end, I thought I had a pretty good set of slides. Many of the appetizers and side dishes ended up as hidden slides – something good to keep for another day.

Many crossed-out eyes mark the slides I chose to skip and may use another day.

A day of shooting

This was my first screen capture on Linux. I’ve used TechSmith Camtasia on Windows in the past. Searching Software for “screen capture,” I found OBS Studio. It was easy to set up and record the slide presentation with myself as a talking head in the lower right corner. I’ll write a separate post about how to do that.

The hard part was getting over my stage fright, or proceeding in spite of it. My voice box felt tight the whole day. Listening to myself, my voice sounded reedy and uncertain, and I clung to the words on the slides instead of describing my thoughts. Standing at an improvised podium in my bedroom, I resolved to continue recording to the very end, instead of restarting every time I flubbed a line. “Try several times and move on. I’d fix it on the edit,” I thought.

The OBS “inception” view you see before you switch to viewing your presentation.

I used Pitivi to edit the handful of clips Pitivi dropped in my home directory. It was fairly easy to cut away my not-so-good takes and slide the better parts together into one somewhat cohesive presentation.

Finally, I clicked the Render button and waited for a few minutes while it created an .ogv file. I also had it render an MP4 file. YouTube accepted the .ogv file, even though it wasn’t listed as one of the supported file types. The .mp4 file was about a third larger than the .ogv file, and it looked sharper on YouTube.

Debrief

It was slow and challenging, but worth persisting. I have wanted to do this for a long time, and am glad I finally pushed through my discomfort with being in front of the camera. I expect I’ll get faster and better with practice. This is a key skill for some of the work I want to do going forward.

Now, I need to start working on a re-shoot or perhaps a voice-over of the original…if I can get my voice box to loosen up.

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.

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: