Technical writing

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?

Pie chart of authors of API documentation literature showing 160 male, 32 female, and 11 unknown authors — The sex of the authors in my API documentation bibliography.

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.

September 10, 2018

More docs on API docs

I’ve tabulated my entire collection of docs on API docs for your perusing pleasure in my API documentation bibliography. The documents for which I could find links to online copies have links. The rest have restricted access. Fortunately (and somewhat surprisingly) only 14 (12.5%) of the 112 articles I’ve found so far are restricted.

The articles are sorted by year published and title so the most recent publications will appear at the top. I’ll check in every once in a while to see what’s new in the field and update the list as necessary.

I’ve reviewed each of these to varying degrees of detail. Some are, admittedly, very detailed and read like a functional software specification (i.e. as dry as the Atacama), so in those, I read just enough to pull out the classification details.

I didn’t plan this (nor was I expecting it), but the author-affiliations of all these articles break down as:

47.3% of the articles were written by academic authors
42.0% of the articles were written by industry authors
8.9% of the articles were written by a mix (collaboration?) of industry and academic authors

Continue reading “More docs on API docs”

September 9, 2018September 9, 2018

How to read survey data

As it gets closer to our (American) mid-term elections, we’re about to be inundated with surveys and polls. But, even between elections, surveys are everywhere, for better or worse.

To help filter the signals from the noise, here is my list of tips for critically reading reports based on survey data that I’ve collected over the years.

If you’re a reader of survey data, use these tips to help you interpret survey data you see in the future.

If you’re publishing survey data, be sure to consider these as well, especially if your readers have read this post.

To critically read survey data, you need to know:

Who was surveyed and how
What they were asked
How the results are stated

Let’s look at each of these a bit more…

Continue reading “How to read survey data”

August 17, 2018

So, what does this mean?

Continue reading “More articles on API documentation”

August 6, 2018

New articles on API documentation

These are some the new articles I found while browsing Google Scholar on the subject of API documentation since my last update on the topic. I found about 20-some new articles since January, which is exciting! Here’s a review of just the ones I’ve had a chance to skim and write up, so far.

This recent trove of documents makes me happy and sad as did the papers I reviewed in an earlier post. These articles contain lots of great research into API documentation, who uses it, and how it’s used. All of these are available for download and I would encourage you to do that if you are interested in API documentation.

At the same time, I’m still disappointed that there has been absolutely zero research published on the topic from the technical communication community this year (was I really the only one who was doing that lately?!) and little to no reference to anything tech-comm related in these papers. If you know of some API research published in a tech-comm venue (and that’s not already in my list), please let me know. At this point, all this is just a warning that some of my disappointment might seep through into my article reviews.

Many of these articles (3/4) had both academic and industry authors, which suggests that industry-academy partnerships aren’t that unusual in the research of API Documentation—if you’re in computer science. In tech comm, as Tom Johnson’s recent survey laments, not so much.

Some of these articles cite earlier research in developer user studies and also contribute to that body of work. None of them, however, cite what I would call writing or reading research. That wouldn’t be so troubling, if it were just these articles, but I can’t think of an article on the topic of API documentation published in a computer science venue that talks about actually reading and using the content. At the same time, there now seems to be a recognizable genre in API documentation literature that Head et al. describes as, “finding anti-patterns in documentation” (see reviews below).

So, here’s a short review of four of the articles I read this morning.

Continue reading “New articles on API documentation”

August 4, 2018August 6, 2018

The first piClinic articles have gone live!

Although I’ve been in the field conducting research for the past month (in places, such as depicted in the photo), I still managed to publish and “present” several research papers that have to do with the piClinic Console. More are still in the pipeline, so stay tuned…

In Using Independent Studies to Enhance Usability Assessment Skills in a Generalist Program, co-authored with Dr. Pam Estes Brewer, Associate Professor in my department, we talk about how we used the development of the piClinic Console as an independent-study project for one of her usability research students. Dr. Brewer presented this paper July 23 at the IEEE PROCOMM conference in Toronto. The short story is the project provided an excellent challenge for her student and her student provided vital usability research data that informed the design’s iterations throughout the year. The paper also describes some of the other projects we’ve used to help develop future usability researchers.

Enriching Technical Communication Education: Collaborating Across Disciplines and Cultures to Develop the piClinic Console, was just presented in Milwaukee, WI at the 36th ACM International Conference on the Design of Communication. Instead of a personal appearance, I sent them this video to present in my stead. The paper details the design process and how it was applied to our technical communication curriculum. For example, as the usability research independent study project described in the preceding paper. Other tech comm lessons the project has produced include some visual UI design, the production of the promotional video that appears on piclinic.org, and several projects for the computer engineering department. The video, on the other hand, provides some of the back story behind the project.

For more interesting articles, see the complete list of my publications.