Author: bobw

Posted on

Filmmaking lessons that improved my technical writing

Bob sitting next to 16mm movie camera
Cinematographer Bob on location

Some time ago, I was a filmmaker. Honestly, I wasn’t especially good at it. I wasn’t bad, just OK. However, while I enjoyed the work, using my checkbook balance as a metric, I wasn’t good enough at it to make a living. Because of that, I’m a technical writer.

Filmmaking, however, taught me a lot about technical writing, so I thought I’d share a few of the lessons I learned.

A high-quality film is not the same as a good film

I’m sure you can recall a film that was awful. It could have had excellent lighting, exposure, audio, soundtrack, etc. but you still wonder how you’ll ever get back those 90 minutes of your life. There are many excellent technicians in the film industry who produce technically high-quality material. And yet, somehow all that high-quality material results in a film that is painful to watch endure.

What I learned was that ALL the elements of a film must work towards the goal of telling the story or the film doesn’t work. It’s surprisingly binary. Just being good in a few categories is rarely enough to carry a film.

Except for the story, being good in one aspect rarely makes up for being bad in another. I was a filmmaker before YouTube and home-made videos–around the time reality shows started becoming popular. The importance of story over technical quality (caveat: the audio must always be acceptable) was clear. Since then, what you see trending on YouTube should convince you that story is still king.

With technical docs, I see a lot of concern over “technical” quality, such as spelling, language, vocabulary, and bugs fixed. I’m not saying these elements aren’t important. But, if you’re not telling your audience what they want to know, how well it’s spelled isn’t going to matter. I was surprised to see a similar discount of technical quality in my dissertation study (see API reference topic study – summary results). The problem, unfortunately, is that it’s easier to count these technical qualities, so it’s deceptively attractive to equate technical quality with document quality or utility. Technical quality might be a factor in utility, but it’s not a proxy.

Don’t give the audience a reason to leave

A film must tell a story in a way that keeps the audience wanting to know what’s next. Whether the film is a 10-second commercial or a 90-minute feature, crafting a story in such a way is a skill that takes practice and a knowledge of your audience. It’s an aspect of the film that starts with the script and must be supported all the way through production, editing, and release. It’s one of those things that, if not done well, can result in one of the bad examples I referred to in the previous lesson.

Continue reading “Filmmaking lessons that improved my technical writing”
Posted on

Migrating my WordPress site, again

I’ve been trying to develop a regular rhythm to posting, again. Last week, however, I had to stop for some badly needed maintenance and cost reduction by changing web site hosts. This turned out to be a remarkably painless experience, thankfully.

A little over a year ago, I moved my site from a hosted service to my own Amazon EC2 instance, as I talked about in How do I look, now? That move was desperately needed and it wasn’t too difficult, either. What I underestimated (or underappreciated) was the need to keep up with the OS updates, WordPress updates, certificate updates, etc. The cost wasn’t much different from what I’d been paying and it gave me the access to the nuts and bolts that I felt I needed after the previous hosting service lost two months of content that I described in What’s with the radio silence?

But, with power comes responsibility. In this case the responsibility to keep all the aforementioned nuts and bolts properly tightened–a task that seemed to take up much of my scarce and fragile attention span.

So, as of last weekend, docsbydesign.com is now running on a managed WordPress site hosted by EasyWP. Migrating my site was made easy by using All-in-One WP Migration. The migration tool makes a complete backup of the old site’s files and database, which also serves as a handy site backup, and then updates the destination site to look just like the old one. So close to the original, I had to add a new file to be able to tell them apart. The only challenges, if you can call them that, involved resetting my DNS to point my domain to the new host and get a new certificate for the site. These two challenges were solved with a couple of emails to their support team who responded quickly.

Continue reading “Migrating my WordPress site, again”
Posted on

Documentation metrics, again?!

A digital voltmeter being prepared to measure a web page.
If only this was all you needed to measure a web site.

To get back into the blogging habit, I thought I’d rummage through some of my earlier posts to see if there might be something I could recycle. (How does the saying go? Good designers copy, great designers steal?) Because the topic of documentation metrics came up recently at work, I thought I’d start there and see if I had said anything about that before.

It turns out, I’d written a post or two on the subject, so let the theft recycling commence!

In The answer is Google Analytics—what was the question? I talk about how the web interaction model that Google Analytics (GA) is optimized for comes up short for a lot of user assistance content. True confession: GA is wired up to this site, and in Google Analytics just makes me sad, I followed up with a summary about how that works for me. Hint: the title sort of gives that away.

The premise of conflicting models came from a paper that my Ph.D. advisor and I wrote about the challenges of collecting useful data about your non-funnel-oriented web content. I posted a blogified version of the published paper in the series on Readers goals. Basically, if the reader’s reason for reading an article is to accomplish a goal that’s outside of the documentation, it’ll be difficult to measure how the documentation helped that goal from inside of the documentation.

I was on a roll, four years ago, because, I continued with Measuring your technical content – Part 1, Part 2, and Part 3. Part 1 talks about asking the questions you want your analytics and analysis to answer and the instrumentation that can help make that happen. Parts 2 & 3 bring this exercise into a sharper focus by trying it out on getting started topics and tutorials, respectively. That thread addresses some of the challenges that you might encounter along the way in Measuring your technical content – What about…?

Continue reading “Documentation metrics, again?!”
Posted on

Tap, tap…is this on?

I’m back at the blog, after a year, five months, and a couple of days. As my first blog post in a while, please be patient. It might be a bit rough.

How time flies. To catch up…

I’ve been working as technical writer since last January. Although I enjoyed working as an academic, it became clear that academia and I weren’t really cut out for each other. So, I’m back in the Pacific Northwest writing technical documentation for Amazon Web Services.

Returning to industry

It was almost as if I’d never left. I have to credit the amazing group of people I work with for making the transition a smooth one. Working in big tech is pretty much as I recall: lots to do, little time to do it—so, maybe not that different from academia.

While Amazon, in general, is famous for its short average tenure, on our team, the low average tenure is simply because we’ve been hiring new writers and we’re looking for more. We’ve got a lot of work to do! Good people, interesting work, decent pay…can’t complain, and did I mention that we’re hiring?

I’m finding the work interesting in all the dimensions that intrigue me: Technical novelty, information design, and collaboration with engineering.

The part of the product I work on has been around for a while and is still growing, so addressing the information needs of both new and experienced users presents some interesting challenges–made even more interesting by the short schedules. The collaborative group of engineers, designers, and writers I work with, however, make tackling these challenges both enjoyable and possible.

What’s new in the scholarly literature?

While catching up, I thought I’d see what’s new in the API documentation research. A quick (and by no means comprehensive) survey of the academic work that’s been published on API documentation since the list of New articles on API documentation I posted three years ago shows that software developers:

  • Still want better docs with more code samples.
  • Are still trying to create them with automation (instead of tech writers)
  • Are still not citing work from actual technical communication research.
  • Still don’t seem to do much research past surveys.

Sigh. Everything old, is new again.

I’ll organize this more later (and hopefully change some of these initial impressions for the better). In the meantime, I’m waiting for the research that explores Why is this still the case after over a decade of research pointing out the issues (repeatedly)? This 2018 paper by Murphy et al. is in the right direction by exploring some of the challenges that practitioners face trying to design usable APIs–a prerequisite for making it easier to create usable API documentation. Maybe there’s a research opportunity for a similar study with technical writers.

Nevertheless, it’s good to see all the research being published on API documentation. It’s much better than the comparative handful of articles that were available on the topic when I started researching it in 2008.

Murphy, L., Kery, M. B., Alliyu, O., Macvean, A., & Myers, B. A. (2018, October). API designers in the field: Design practices and challenges for creating usable APIs. In 2018 ieee symposium on visual languages and human-centric computing (vl/hcc) (pp. 249-258). IEEE.

Posted on

How do I look, now?

Hopefully, the same. Over the weekend, I migrated my web site from a brand-x hosting service to a DIY server hosted by Amazon Web Services (AWS). After the disappearance of my site last spring, I’ve been looking for an excuse to find it a new home, but didn’t want to spend a lot of time fussing with the details of site management and migration. Turns out (as so many things do), it was much easier than I anticipated. The migration was straightforward and accomplished in just a short time, once I knew what I wanted to do.

AWS offers a dizzying array of configuration options, which can be very intimidating to the weekend webmaster. So, the first problem was to figure out which server options I wanted to use (i.e. pay for). I opted for tiny, which seems to work well enough. Being virtual servers, I can always level-up (or down) if performance becomes an issue. In all fairness, the hardest part was trying to figure out what I really wanted.

Once I got the server running to my satisfaction, Step-by-Step Guide to Migrate Your WordPress Site to a New Host provided the details to migrate the site contents (files and database tables). The hardest part of that process was realizing that I needed to create an .htaccess file on the new server.

Going through a Cloudflare load balancer made switching to the new server as easy as typing in the IP address of the new server. A couple of summers ago, I moved the public IP of my site to Cloudflare to take advantage of their SSL support. That gave my site its padlock (finally) and a bunch of other features–like the presto-chango IP address. No DNS records involved at all. Best of all, if I messed something up, I just type in the old server’s IP until I get things sorted out.

So, this is my first post of the new year (2020…and I’m still upset that don’t have a flying car that I was promised in the 1960s views of the 21st century). And, my first post on the site’s new server.

Happy and prosperous new year!

Posted on

First time scuba diving

Dolphin swimming by near surface for a photo
Dolphin swimming by for photo near surface

On the island of Roatán, this summer, I finished a research project that I’d started five years ago. Having some well-earned down-time, I visited Coconut Tree Divers in the town of West End to earn my PADI Open Water Scuba Diver certification. Having snorkeled in Roatán, I found the colorful aquatic life found in the coral reef to be quite enchanting and only yards from the beach; however my excessive buoyancy prevented me from exploring more than several feet below the surface. I thought that Scuba Diving would enable, at the very least, descending more than a few feet beneath the surface.

I was surprised by how comfortable I felt under water. I’d always been rather anxious snorkeling because, mostly due to ill-fitting rental gear and poor technique—both of which contributed to swallowing a lot of sea water. With scuba diving, I still had floppy rental gear, but having your air always available, drinking sea water was no longer a problem, and that anxiety disappeared.

The instruction for this course covers the basic techniques to stay alive while underwater, practiced to the point that we could take care of ourselves within limits that minimize risk. Being next to the beach and boat dock, and having many deep diving sites less than 10 minutes away, certification took only a couple of days leaving time for “fun dives.”

After the certification, however, there is still more to learn and much more to practice. The next week I went back for the PADI Advanced Open Water certification.  With the Open Water Scuba Diver certificate, you can dive without an instructor to a depth of 60’ (18m). In Roatán, staying above 60’ deep will barely cramp your enjoyment as you can see most of the coral and many reef animals in this area. Also, as you descend, the color spectrum becomes only shades of blue and green, your air consumption increases, and the time you can spend underwater due to Nitrogen absorption decreases. Bottom line: there is much to see in the 30-60’ depths around Roatán, so the Open Water Scuba Diver certificate is the ticket to a lot of interesting sites and sights!

Looking at the bow of a sunken ship from above and behind.
An example of what you can see while in Roatan at 100′ underwater

The Advanced Open Water certificate does open up greater depths (up to 120’); however, it also includes additional skills—buoyancy and navigation, for example. After my advanced certification, I felt much more comfortable finding my way around underwater. While I wasn’t particularly stressed out under water after my initial certification, after my Advanced course, I could now relax. I’ve described it as doing yoga with fish and sea turtles.

At neutral buoyancy, you’re weightless, for all practical purposes. At neutral buoyancy you can ascend and descend simply through breathing. As an added bonus, the more you relax, the less air you use, letting you stay underwater longer. Watching the pro divers (dive masters and instructors) on our dives, you could see how they moved as little as possible while still getting to where they wanted to be. Us newbies, however, were another story.

I’m now hooked on it and strongly recommend Coconut Tree Divers in West End, Roatán, if you’re looking for your ticket to another world!

Posted on

What’s with the radio silence?

Tropical beach with sunny sky and plapapas
Summer in paradise

I’m finally catching up with myself after an action-packed summer. I’d intended to share much of my summer activities through my blog because, well, it was action packed. However, one of this summer’s actions was the disappearance of my website (more on that later). So, as my site updates its version of WordPress, I thought I’d start catching things  up.

TL;DR

In a nutshell, my wife and I went to Honduras for the summer to finish the research on the piClinic Console I’d started a few years ago. Thanks to a Fulbright Scholars Grant, we were able to travel to Honduras for the past two summers to see if I could disrupt healthcare information systems technology in rural clinics.

Short answer, yes.

Of course, many other things happened as well. I’m not sure how many of those adventures will fit in here, but these are some of the things I’ve done since my last (currently published) blog post.

  • Spoke at the API the Docs conference in Chicago in April.
  • Read a few good books:
    • Ruined by Design: How Designers Destroyed the World and What We Can Do to Fix It by Mike Monteiro
    • Measures of Success: React Less, Lead Better, Improve More by Mark Graban & Donald J. Wheeler
    • Everybody Lies: Big Data, New Data, and What the Internet Can Tell Us About Who We Really Are by Seth Stephens-Davidowitz
  • Wrote some thoughts about them in my blog.
  • Woke up to find this site had disappeared.
    • Got chewed out by my hosting company for not reading the various email they claimed to have sent (but that never arrived).
    • Spent the next two weeks on Skype and my slow Internet connection dealing with the aforementioned hosting company trying to find my site.
    • Learned they migrated my site using a backup from two months earlier (sending my last two months of posts into the bitbucket).
  • Hosted 10 undergraduates on a Mercer On Mission trip to Honduras, in which they conducted research on the piClinic Console and got a taste of Caribbean culture on the Honduran island of Roatan.
  • Spent three weeks on the Honduran mainland during some political demonstrations.
  • Learned how to SCUBA dive.
  • Attended SIGNAL 2019.

So here I am; doing my best to get caught up.

Posted on

The documentation cliff

For the past couple of months, I’ve been refactoring the piClinic Console software to get it ready for this summer’s field tests. Along the way, I encountered something I’d seen before, but never really named, until recently.

The documentation cliff.

A documentation cliff is where you get used to a certain level of documentation quality and support as you embark on your customer journey to use a new API and then, somewhere along the way, you realize that level of support has disappeared. And, there you are, like Wile-E-Coyote, floating in air, looking back at the cliff and looking down at where you are about to fall in the next instant.

Just kidding. What really happens is that you realize that your earlier plans and schedule have just flown out the window and you need to refactor the remainder of your development plan. At the very least, it means you’re going to have some uncomfortable conversations with stakeholders. In the worst-case scenario, you might need to re-evaluate the product design (and then have some uncomfortable conversations).

Most recently, this happened to me while I was using Postman to build unit tests for the piClinic Console software. I don’t want this to sound like I don’t like Postman–quite, the contrary. I love it. But that just makes the fall from the cliff hurt that much more.

How I got to the cliff

In my case, the tool was easy to get started with, the examples and tutorials were great, the online information was helpful–all the things that made a very productive on-boarding experience. So, I on-boarded myself and integrated the product into my testing. In fact, I made it the centerpiece of my testing.

Continue reading “The documentation cliff”
Posted on

Cue-Are-Pee?

Recently, my ham-radio hobby took a turn into the world of QRP (pronounced, cue-are-pee) as the hobbyists call it. QRP is a world where portability and low-profile are preferred over the big and large. The name is from the set of three-letter abbreviations adopted by amateur radio enthusiasts that codify a variety of ham-radio situations and each code start with the letter Q.

QRP means low power.

While General and Extra-class amateur radio operators are licensed to operate on the short waves (below a frequency of 30 MHz) using a transmitter power of 1,500 watts, power levels of 5 watts or less are used in the world of QRP. For comparison, AM broadcast stations transmit with up to 50,000 watts and FM broadcast stations transmit with up to 100,000 watts.

QRP stations are essentially whispering.

What’s the attraction? Mostly that it’s more difficult. QRP stations can’t rely on output power alone to help push their signals into the world so amateur radio operators like to credit their skill as being the differentiating factor. While there’s some truth to that, there are also many other factors the help the signals along the way.

One benefit of QRP stations is that they are very small, and comparatively lightweight making them easy to carry. The radios are generally battery-powered, easy to pack, and easy to carry. More traditional, home-based ham radio stations use a 100-watt radio, such as the one I use from my house. Unlike my lightweight, battery-powered, QRP radio, my ham radio at home requires an AC power supply or a very large (i.e. heavy) battery. A so-called legal-limit, 1,500-watt station requires an electric power that is comparable to what you would use for an electric clothes dryer–making it something less than portable. For the “ham on the go,” QRP is an easy way to take your hobby on the road.

Because QRP operations are the ham-radio equivalent to whispering, not everyone can hear you. However, with the right combination of weather conditions, frequency, antenna, skill, and luck, 5 watts of radio-frequency energy can go quite a long ways–even further if the receiving station has a powerful antenna to help hear your whisper among the other stations.

My QRP station

My portable station, in the photo below, consists of:

Continue reading “Cue-Are-Pee?”
Posted on

If we could only test docs like we can test code

Postman logo
Postman logo

As I continue to catch up on delinquent and neglected tasks during the inter-semester break, I’ve started porting the software from last year’s piClinic Console to make it ready for prime time. I don’t want to have any prototype code in the software that I’ll be leaving in the clinics this coming summer!

So, module by module, I’m reviewing the code and tightening all the loose screws. To help me along the way, I’m developing automated tests, which is something I haven’t done for quite a while.

The good news about automated tests is they find bugs. The bad news is they find bugs (a lot of bugs, especially as I get things off the ground). The code, however, is noticeably more solid as a result of all this automated testing and I no longer have to wonder if the code can handle this case or that, because I’ll have a test for that!

With testing, I’m getting to know the joy that comes with making a change to the code and not breaking any of the previous tests and the excitement of having the new features work the first time!

 I’m also learning to live with the pain of troubleshooting a failed test. Anywhere during the test and development cycle a test could fail because:

  1.  The test is broken, which happens when I didn’t update a test to accommodate a change in the code.
  2. The code is broken, which happens (occasionally).
  3. The environment is broken. Some tests work only in a specific context like with a certain user account or after a previous test has passes.
  4. Cosmic rays. Sometimes they just fail.

The challenge in troubleshooting these test failures is picking the right option from the start to make sure you don’t break something that actually was working (but whatever was really broken is hiding that fact).

But, this is nothing new for developers (or testers). It is, however, completely foreign to a writer.

Here are some of the differences.

Continue reading “If we could only test docs like we can test code”