Today is Red Hat’s “Day of Learning.” We are encouraged to dedicate this day to learning.
This past year, I’ve been mentoring one of my peers. Earlier this week, I asked her to share her thoughts on what went well and what could be better. I got her notes this morning and spent some time reflecting on them and sharing my thoughts.
I listened several hours of The Servant: A Simple Story About the True Essence of Leadership, by James C. Hunter
One of the nice things about the Write the Docs – Portland conference two weeks ago, was it’s unconference.
An unconference is a participant-driven meeting. The term “unconference” has been applied, or self-applied, to a wide range of gatherings that try to avoid hierarchical aspects of a conventional conference, such as sponsored presentations and top-down organization.
This morning, I wrote the conference organizer and pulled my presentation. My early morning thoughts had revealed to me how I had missed the mark.
During the process of creating the presentation, I had this uneasy sense that I was missing something. My early morning thoughts crystallized my understanding of what was amiss and I saw the way forward.
To sum it up, my realization was this: Try it again. Do it the open-source way. Don’t develop a presentation in isolation and toss it over the wall to an uncertain audience! Instead, engage the oVirt team, learn about the issues, and work together on solutions. Then, bring that insight to presentation and make a relevant contribution to the oVirt community.
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.
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.
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.
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.
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.
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.
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.
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:
People: Experienced technical writers and software teams who need to document open-source software.
Processes: Open source contributions with an agile workflow following the open-source guide.