Categories
conferences documentation technical writing

Overview: Write the Docs, Portland 2020

This year’s WTD conference was online/virtual only. This shift to virtual conferences make them more inclusive and accessible to attendees whose work, personal responsibilities, finances, or other constraints would normally discourage them from participating. Although this conference was well-attended by folks on the West Coast, by my estimate, half of the attendees were from other regions in the US and Canada; and a handful were from other parts of the globe. I enjoyed breaks and mealtimes with my family and sleeping in my own bed.

Day one, Sunday, August 9th was a pre-conference day with two sets of ten breakout sessions.

The writing day sessions were my favorite part of day one: We got to meet members of the doc teams from GitLab, Microsoft, and Mozilla and contribute to their open-source projects. It was interesting to see the similarities and differences in our tools and workflows.

The event hosting platform, hopin.to, worked well. I stubbed my toe on a few potential improvements, but quickly adapted and had no trouble navigating the event site. The sessions were all live hosted on YouTube, which made it easy to pause the live feed, step away, and then return. I couple of times, after taking a quick break, I caught up with the live session by setting the playback speed to 1.25 or 1.5x. If you’re interested, WTD will probably published the recordings from this year’s event in a month or so. If you’re interested, you can also watch these recordings of last year’s conference.

Days two and three featured a series of fascinating speakers on the main stage.

There was also an unconference, where anyone could sign up for a “table” to give brief talks or discuss anything of interest. For example, shown below is the unconference schedule for the first half of day one.

These unconference tables were the best forums to discuss subjects of interest and meet fellow documentarians (the preferred term for everyone involved in this business). I got to meet more than a few of the main speakers to ask questions about their work.

I’ll probably write a few more posts about some of my favorite sessions. If you’re interested, here is a link to the complete three-day conference schedule.

Categories
documentation open source presentation video

I pulled it

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.

Categories
documentation open source presentation technical writing video

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.

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.