I love it when things just work

Bob Watson piloting a light plane on a sunny day as it approaches the runway to land

The image is a still frame from a video I pulled out of my archive to edit and an example of things just working–I’m on the final approach to a silky touchdown at Orcas Island airport.

In user experience parlance, they call that customer delight. I recently had some experiences as a customer that delighted me. It was amazing!

I hope that my readers get to experience similar delight when they read my docs. Let’s unpack these recent delights to see how they might help improve my writing.

The experiences

It really started with a recent disappointing purchase experience, but first some back story.

About 20 years ago, I used to edit videos, among other things. Back then, computers took a lot of tuning (i.e. money) to meet the processing demands of video editing and effects. After several software and hardware iterations, I finally had a system that had the industry standard software running on a computer that could keep up with the challenge of video editing.

With that, I could finally focus on the creative and productive side of editing without having to fuss with the computer all the time. It’s not that I minded fussing with the computer–after all, that’s what I had been doing all along to get to this state of functionality and reliability. Rather, I don’t like fussing with it when I have other things that I want to accomplish.

It was truly a delight to be able to focus on the creative and productive aspects of the job. Having reliable tools made it possible to achieve flow. If you’ve ever achieved that state, you know what I mean. If not, read Finding Flow: The Psychology Of Engagement With Everyday Life by Mihaly Csikszentmihalhi.

Fast forward to this past week.

I finally upgraded my very-consumer-y video editor (Pinnacle Studio) to edit some home videos. I’d used an earlier version a few years back and I recall it having a pretty low learning curve for what I wanted to do. But my version was getting stale, and they were having a sale, so…

I paid my money, got my download, and was ready for the delight to begin!

Not so fast. There would be no delight today.

Continue reading “I love it when things just work”

Is there any more room for innovation in tech writing?

I was looking through some classic (i.e., old) examples of technical writing and noticed how the format of application programming interface (API) reference topics hasn’t really changed since these examples were published in 1988 and 1992.

Is this because there’s been no innovation in technical writing during the intervening 30-ish years or, perhaps, we’ve found something that works, so why change? Taking that a step further, if what worked 30 years ago still works, is there any more room for innovation in tech writing?

Here are a couple of examples that I found in my library of software documentation. (It’s a library of printed documentation so there’s not much in there from the 21st century.)

MS-DOS Encyclopedia (1988)

Reference topic from MS-DOC Encyclopedia

The first example of classic documentation is from the Microsoft MS-DOS Encyclopedia (Ray Duncan, Microsoft Press, 1988), a 1,570-page collection of everything you’d need to know about programming for MS-DOS (v3.2) in 1988.

It starts with how MS-DOS was originally developed, continues with conceptual overviews of the different operating system functions, how to create common applications and extensions to the operating system, and various reference topics, such as the interrupt example I included here. It’s a one-stop reference manual that would prepare any MS-DOS programmer or device-driver developer for successful coding experiences.

This 33-year-old encyclopedia presents information in a format that you can still see used today.

  • Overview
  • Conceptual content
  • How-to articles of common tasks
  • Reference topics on various aspects of the product
  • Cross references as make sense

The content in the example reference pages that I included also follows a format that is still seen today:

Continue reading “Is there any more room for innovation in tech writing?”

What do you think of our docs?

In most technical writer interviews I’ve had for an organization with public-facing docs, I’ve been asked, “Did you get a chance to read our docs,” which they invariably follow with, “So, what did you think of them?” How should you answer? Here’s what I’ve learned, the hard way.

The answer to the first one, should be a confident (and honest), “Yes!” For, hopefully, obvious reasons. When I’ve interviewed candidates, I have to admit that I wonder why anyone would answer no (and some have). I don’t expect a detailed content inventory but opening a web site and flipping through a couple of pages seem like the least a candidate who is interested in writing them could do—if for no other reason than to see what they’d be getting themselves into.

As to the second one, that has always felt like a bit of trap. For good reason! Here are some possibilities and the traps that lie within.

Their docs are great!

They might be. If so, that’s a good place to start and you should keep going. Saying, “they’re great!” and then smiling politely tells me you either didn’t look at them and don’t want to sound rude or you did but weren’t looking at them with a very critical eye.

What can you say if they really are impressive? Talk about what makes them great and be specific. Some things to talk about include (in no particular order):

  • The visual design: Is it attractive? Is it functional? Does it help you find the information on the page?
  • The content on the pages: Is it easy to read? Is there sufficient white space? Does it have illustrations? Does it have code samples? Can you understand it? …even if you’re not familiar with the topic?
  • The organization and navigation: Are they clear and helpful?
  • The performance: Is the site responsive?

These are some generic qualities that apply to almost any type of documentation. To get more specific, you’ll need to find out more about their audience and documentation goals.

Don’t assume you know what they’re trying to accomplish with their docs! (This is the mistake I used to make. Every time.)

Rather, this is where you turn the conversation back to them and have them describe things like their:

  • product goals
  • documentation goals
  • audience
  • product
  • competition
  • work/task scheduling

These are important aspects of the context in which the documents are produced and used, so you’ll want to know about them before continuing your critique.

The way to impress your interviewer with what you know is by the questions you ask as much, if not more than, the answers you give.

Continue reading “What do you think of our docs?”

Reflections as I begin my third time on jury duty

Diagram of an API as a gear with connection points

Today I met with my co-jurors who’ll be judging this year’s DevPortal awards nominees with me in the coming weeks. The entrants in this year’s showcase represent an impressive effort on the part of the nominees, so we have our work cut out for us. This is my third year on the jury and I’m looking forward to this year’s entries.

What struck me as we kicked off this year’s evaluation today was the 15 different award categories this year–up from last year’s eight categories–and how the presentation of APIs to the world has changed over the years. What impresses me every year is the innovation applied to make this presentation effective and engaging.

Pronovix hosts this event and they’ve modeled this year’s 15 categories around the Maturity model for devportals, which describes these three dimensions of developer portal maturity.

  • Developer experience
  • Business alignment
  • Operational maturity

When I judged the entries last year, I approached it from a usability perspective–how easily could the customer do what they needed to do? From that perspective, the maturity model dimensions represent the usability of the site from the perspectives of different stakeholders involved with an API developer’s portal.

From the perspective of ease of use, developer experience represents how easy the site makes it for the reader to get value from the product. Operational maturity represents how easy it is for contributors to add value to the developer portal. Business alignment represents how well the site makes it easy for the organization to access value.

To be successful in today’s crowded API marketplace, a developer portal must serve all three of the stakeholders these dimensions represent. The maturity model dimensions reflect how APIs must do more than just provide access to a service.

Each year, the entrants in this competition get better and the competition gets even more difficult to judge. It’s clear that the entrants are taking notes and applying what they learn.

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”

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”

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?!”

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.

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!

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!