improving, reinventing, and transforming technical communication
The past two weeks, I created a Slack channel called #vale-at-red-hat and invited folks at work to join. Then I invited them to become collaborators on the repo.
It worked! A bunch of folks signed up to become full collaborators.
To work this way, you have to give up sole ownership and control. Invite folks to collaborate and contribute as equals. Be generous with recognition and credit for work done!
Let’s see what happens next!
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.
https://en.wikipedia.org/wiki/Unconference
This is exactly the right place to workshop new ideas with peers and stakeholders.
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.
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.
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.
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:
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.
“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.
In a future post, I’ll write about how to analyze and use these upstream docs to create better customer-facing docs.
