Technical writing

August 29, 2021August 30, 2021

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.

August 15, 2021August 15, 2021

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…?

August 7, 2021

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.

March 5, 2019September 27, 2019

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.

December 27, 2018

If we could only test docs like we can test code

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:

The test is broken, which happens when I didn’t update a test to accommodate a change in the code.
The code is broken, which happens (occasionally).
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.
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.

December 23, 2018February 11, 2019

Recent good, could-be-better, and ugly documentation experiences

During the “break” between semesters, I try to catch up on the tasks I’ve deferred during the past semester and get ahead of the tasks I know will come up during the coming semester. In the process, I’ve had these encounters with documentation that I’ve characterized into these categories:

GOOD: documentation doing what it should—making me(the customer) successful.
COULD-BE-BETTER: documentation that is well-intentioned, but needs a tweak or two.
UGLY: documentation that gives me nightmares.

Here goes.

Good documentation

These are the stories of documentation that made me successful. Being successful makes me happy. Good documentation should help make the reader successful.

Ford Motor Company. F-150 owner’s manual

The windshield wipers on my almost 3 year-old truck are the ones that it came with from the factory— almost 3 years ago. Well past their expiration (and effectiveness) date. But, while I’ve changed car engines and gear boxes before, I hate changing wipers. They always have some clever (and obscure) trick to getting the old ones off and the new ones off. I especially hate it when they go flying off the car in a rain storm. So, for all these reasons,I’ve procrastinated on changing them for far too long (as driving in recent wet weather has reminded me)—the replacements have actually been in my garage since…I actually can’t remember.

November 25, 2018November 25, 2018

I just can’t see myself as a customer

How often have you been shopping and, while looking at something that might be suitable, you just had the feeling that it wasn’t right? When shopping for houses last year, we had that feeling many times (too many times). They were, for the most part, all nice homes, but they just didn’t do “it” for us. Sometimes we could articulate the reasons, other times, it was something less tangible. In every case, except for the last one, of course, we walked away without becoming a customer.

We finished house hunting about two years ago and I hadn’t given that feeling a second thought until I came across a blog post about making the Build vs. Buy Decision. Point 4 of that post, whether it is cheaper to build than to buy, got me thinking about one of the value propositions that technical communication frequently asserts–to increase product adoption. To tie it back to house hunting, let’s call it making it easy for potential customers to see themselves using your product and becoming a customer instead of just a prospect.

Try it, you’ll like it!

In API marketing, one of the methods recommended to promote your API to potential customers is to provide some easy way for potential customers to take a test drive. Options such as providing a sandbox, having an accessible Hello World application or example, and providing tutorials that provide solutions to common customer pain points. The idea is to get them into the driver’s seat and let your potential customers take it for a spin. The lower the barrier to entry, the easier it is for your potential customers to see if this is a product for them and to see themselves as satisfied customers.

Continue reading “I just can’t see myself as a customer”

October 15, 2018

What’s your story?

For a few years, I tried my hand at filmmaking. I was OK at it; however, it was during a time when the competition was amazing. OK, wasn’t good enough. Fortunately, I had a backup job and, after a couple of years of being OK at filmmaking, I returned to technical writing. I was surprised to find that after being a filmmaker for a while, my technical writing had, somehow, improved, even though I did absolutely zero technical writing as a filmmaker.

Here are some of the lessons I learned as a filmmaker that apparently had more value when applied to technical writing.

All that matters is what people see on the screen

As an independent filmmaker I watched many independent films. Those scars will be with me for the rest of my life (If you’ve watched indie films, you know what I mean. If you haven’t, you’ve been warned). Some of my films must have scarred others (sorry). I believe filmmaker Robert Rodriquez said in Rebel Without a Crew, that you needed to make several hundred films before you become a filmmaker. I would agree. I still had a few hundred more to go before I ran out of money.

Before watching others’ films, the Directors (or, more often, director/producer/writer/photographer/star) would give a brief commentary and, invariably, these commentaries included all the things that didn’t go as hoped or as planned—preparing us for what were about to experience (i.e. lowering our expectations). While of some interest to the filmmakers in the audience, this information was irrelevant to anyone else.

What matters to the audience (i.e. those who might actually pay to see/rent/download the film) is what is on the screen. Period.

Tech writing takeaway: the reader will judge the content for what they see and not what you would like them to see.

Continue reading “What’s your story?”

October 12, 2018October 15, 2018

What were they thinking?!

Design reviews or critiques are a favorite pastime. While my righteous indignation of having to suffer a bad website can still evoke some pointed criticism, I’m trying to keep things in perspective.

I’ve talked about critiquing designs in the past, but here, I’m talking about those informal critiques of designs created or constructed by other people or organizations. You know, the ones that usually start with “WTF were they thinking!?!”

The objects of such informal critiques are legend. A search for design fails in Google returns 270,000,000 results to me (in 0.3 seconds, so it must be a popular search). I remember talking about some of these design fails in design classes, but I’ve been involved with designing, building, and shipping long enough to know these examples of design fails are team efforts.

Full disclosure, I still shout “WTF?!” from time to time in spite of the following introspection, but my hope is that reflecting on these points will help me view them with a little more perspective. I write this so that you might, as well.

WTF?!

Let’s start with that point when you’re using a website that is sporting the latest version of Gordian-knot navigation or TV remote control and you’re wondering aloud how anyone could design such a mess, let alone ship it for what seems like the sole purpose of causing you grief. Of course, YOU would NEVER commit such a crime against humanity!

Would you?

Have you? (Be honest.)

If you’ve shipped more than one or two documents, products, web-sites, or you name it, then in all likelihood you, too, have published or shipped something that someone, somewhere, at some time will say WTF?! when they use it. It’s almost impossible not to and here’s why.

Why do people ship bad designs?

Continue reading “What were they thinking?!”

September 28, 2018October 1, 2018

Who writes docs on API docs?

As More docs on API docs described, it’s mostly academic authors writing about API docs, but only by a narrow margin. As I was reviewing the articles I found, my impression was that only men were writing about API documentation.

Because impressions can be mistaken, I went through the articles and reviewed all the authors to determine their gender, insofar as I could. Because this information is rarely reported with the articles, I had to do some digging.

Most of my determination of an author’s gender is based on the authors given name; however, where available, I used their portrait or other references to confirm. For the names that had a recognizable (to me) gender preference, I assigned them accordingly. For those I couldn’t easily tell, I searched for the author’s profile on Google Scholar, ResearchGate, and just plain-ole’ Google to find a social media page. However, after all that, I could not make a credible determination for a little over 5% of the authors so they show up as unknown in the pie chart.

It turns out that my bibliography of 112 articles has a total of 203 unique authors; at least 160 (79%) of which seem to be men, while at least 32 (16%) seem to be women. Or, seen another way,

1 author in 6 who has written an article on API documentation is a woman.

That ratio is roughly consistent with the population of software developers reported in surveys such as Women in Software Engineering: The Sobering Stats (1/6) and 2018 Women in Tech Report (1/7).

So, what does this say?

I’m not sure. It seems like a case of: hey, 1 in 6 authors of articles about API documentation is a woman, which is in the same proportion as the software development field. And, hey, only 1 in 6 authors is a woman, which is in the same proportion as the software development field. Also noteworthy, the earliest article in my list was authored by a woman.