Category: Technical writing

Last night, in an attempt to fix a loose temple on my glasses, I found myself in a pickle. As is often the case, it was much easier to take my glasses apart than it was to reassemble them.

I’d taken the temple off my glasses frame to tighten a loose hinge. However, I realized (after dis-assembly, of course) that the spring tensioner in the temple made it impossible to replace the screw that holds it to the frame. Of course, I tried (stubbornly) for about 30 minutes to figure out how to reassemble my glasses. Alas, to no avail.

Eventually, I asked YouTube and found this video.

In less than two-and-a-half minutes, the video producer demonstrated the problem, the tools needed for the repair, showed how the method worked, and then the final outcome—a textbook-perfect tutorial. No fluff, just useful information. Five minutes later, I had my glasses reassembled and back in business.

The collection of in-flight reading material found in the seat back of a recent Alaska Airlines flight

I’m working on a paper for the HCII 2015 conference and thought of the reading material I saw on a recent airline flight. The paper discusses ways to identify the goals of different types of information-focused web content and how to measure how well the content is accomplishing those goals, so now I see this everywhere I look.

This is what occurred to me while I was staring at this collection of literature for several hours.

The Alaska Airlines magazine

It’s goal is to provide the reader with entertainment, er, I mean provide them with advertising, using entertainment as the bait. So how would you measure success? Interaction with the content, maybe? Coupon codes entered, products ordered from the web links, and other interactions traceable to the magazine. Pretty straightforward. Content can be compared to the corresponding advertisement, reader feedback, and the publisher can decide what’s working and what needs work.

The airsick bag

This isn’t really literature, but a good case of “if it’s not easy to use, it’s going to get messy.” I don’t think any amount of documentation could fix a poorly-designed air sickness bag.

The emergency procedures brochure

This is everyone’s favorite reading material, right? It’s goal is to provide important information and provide it in a way that’s easy to understand (quickly, in the worst-case scenario). This is a document that Alaska Airlines (and its passengers) hope to never need, but when it’s needed, it’s value will be immeasurable. How do you track that goal? User feedback? probably not. Survivor stories? Let’s hope not! Maybe usability testing?

The WiFi and the “Meals & Snacks” advertisements

Again, this is purely promotional material whose effectiveness can be tracked by sales. Like the magazine, this is not unfamiliar territory.

What’s this got to do with me?

As a writer of help content, I relate to the emergencies procedures brochure. Sometimes I don’t think anyone reads my content and frequently, Google analytics tends to agree with me. But, I know that in some cases, when those few people need to read it, that’s going to be the most important thing for them to read (if only for that moment). If I’ve done my job right, what I’ve written will save them time and money. I’ll never know that from looking at Google analytics, but, a usability test (even an informal or discount test) will tell me if a topic will be ready to save the day (moment) when it’s called upon to do so.

For my PhD dissertation, I ran an unmoderated, online study to see how variations in page design and content of an API reference topic would affect how people found the information in the topic.

For the study, I solicited participants from several software development groups on LinkedIn and a few universities around the country. It’s definitely a convenience sample in that it’s not a statistically random sample, but it’s a pretty diverse one. Is it representative of my audience? I’m working on that. My suspicion, in the mean time, is that I’ve no reason to think it’s not, in that the people who read API documentation include a lot of people. For now, it’s representative enough.

A wide variety of people responded to the 750,000 or so software developers and people interested in software development that I contacted in one way or another. From those invitations (all in English, by the way), 436 people responded and 253 actually filled out enough of the survey to be useful. The 253 participants who completed the demographic survey and at least one of the tasks were from 29 different countries and reported speaking a total of 32 different native languages. Slightly less than half of the participants reported speaking English as their native language. After English, the top five non-English native languages in this group were: Hindi, Tamil, Telegu, Kannada, Spanish.

More than half of the participants didn’t speak English as their native language, but the vast majority of them should have no problem reading and understanding it. Of the 144 who didn’t speak English as their native language, 81% strongly agreed with the statement, “I can read, write, and speak English in a professional capacity or agreed or strongly agreed with the statement, “I can speak English as well as a native speaker.” So, while they are a very international group, the vast majority seem to speak English pretty well. The rest might need to resort to Google translate.

All of this supports the notion that not providing API documentation in any language other than English is not inconveniencing many developers—developers who respond to study invitations in English, at least. An interesting experiment might be to send this same survey to developers in other countries (India, China, Japan, LatAm, for starters) in their native languages to see how the responses vary.

Just three days after I post about how I was going to consider the minority, I post how software development documentation should be written and published in just English.

Three days.

Am I ignoring my theme of the year (or the week)?

I don’t think so.

I did consider the rest of the non-English-speaking world (which is actually the majority of the world), when I thought about that. Will anyone be harmed by a lack of API documentation written in Miskito, for example. I don’t think so. If it turns out that they might need it, however, I’ll revise my decision. But, what about in Spanish? Possibly. But, from the information I have available, probably not. Inconvenienced, might be the worst-case scenario.

So, while I won’t be writing any technical documentation for the Miskito people of Central America in the immediate future, they haven’t been ignored in the decision. As a side note, later this year, I will be helping to give them something they need much more than technical writing.

The point of this year’s theme was to consider the vast minority–include them in the design and thought process. So far, I think I’ve done that (for going on four days, now!). The point is to consider them. Include them in the design process. Ask the question, “Will not accommodating the minority hinder, or worse, harm them?” Sometimes it will, such as in the case of accessibility aspects of documentation. Sometimes it won’t, as in the case of translating or writing for people who have no use for the documentation in the first place (i.e. there are other problems to solve before that becomes an issue). In either outcome, they were included in the process.

Latin pop star, Enrique Iglesias made this video of a song in Spanish. As I write this, it had over 648-million views since it was published April 11, 2014. About 65-million/month.

Released a few months later, on June 13, 2014, was this “localized” version in Spanglish (with mixed Spanish and English lyrics). It has had only 90-million views. About 13-million/month.

Now there are a lot of reasons that could explain such a difference (and 13-million a month isn’t shabby, by the way), but in listening to them both, I’m with the majority and prefer the original. Both versions are good, but they are different and they each have a unique feel to them. To my ears, the all-Spanish version has more feeling and is a bit more romantic. In comparison, the Spanglish version doesn’t have the same sentiment, to my ears. You can compare the two sets of lyrics for yourself, if you’re interested: Spanish lyrics and Spanglish lyrics.

What’s this have to do with technical writing? (Thanks for hanging in there, by the way)
In code samples and technical documentation, like music (and many other fields), the original is almost always better than the translation. The best information about developing with a software library or API is going to be in the original language, which invariably is English.

So, as a technical writer of developer documentation for a software product with an international audience, should you write in English and/or localize the technical content? In the absence of evidence to the contrary, my default answer is, Yes you should write the documentation in English and No, you shouldn’t localize it. Localization is guaranteed to be costly and not guaranteed to be anything more than marginally beneficial.

Over the years, I’ve collected a lot of anecdotal information on this, but this is one of the things I’ve wanted to study more formally. Anecdotally, international developers believe that the translations aren’t as good as the original English version and tend to prefer the original English version over the same content translated into their language. One reason might be that software has a lot of keywords, class and method names, and the like in English which can’t really be translated. If you read the original, you know you won’t be tripping over inappropriately translated terms.

I have some info from my recent API documentation study, but it’s a bit tangential to this topic.

Janus, the Roman god of beginnings and transitions.During this pause between years, I’ve been pondering the past year and planning the next. Throughout this [unfortunately brief] reflection, I’ve accumulated tidbits of information and inspiration. All of which could be summed up as “consider that one person.” Instead of a New Year’s resolution, I think I’ll adopt that as my theme for the year.

The seed for that theme was planted a few months ago while I was talking with Dharma Dailey, a fellow PhD student at the UW, about her research on tweets made during disasters. Dharma was telling me about how she was looking for ways to find the minority threads amongst the major ones (I hope I got that right). The notion that there might be something interesting in the minority (i.e. the minute minority) was one to which I hadn’t given a lot of thought. But, the seed had now taken root and was watered by subsequent events, which highlighted the idea that:

The vast minority isn’t just interesting, they are very important.

The next event was all the press that Facebook’s “year in review app” got, recently. Surely, the app was designed for their target demographic (although, I can’t say how Facebook defines that). With equal confidence, I’m sure that the majority of the target demo found it as enjoyable as the product manager had hoped they would. But, where did the most notable press about the app come from? The minority. Starting with one, Eric Meyer.

Thinking of the vast minority or the outliers in this case could have prevented some emotional pain for (at least) one person and some bad (or at least, unfavorable) press for a product and a brand.

Then I got a tweet from @UsabilityCounts with a link to Mike Monteiro’s presentation at WebStock 2013 about designer responsibility. In his video, Mr. Monteiro presents the case of Bobbi Duncan as one who was seriously troubled (suicidal) by the actions of a product (Facebook, again). But, hey, she’s just one person, right? Think about all the millions who like the feature! I confess, I used to think that way, too. But, as Mr. Monteiro points out so emphatically in his talk, thinking about the vast minority, or even just the 1-person, is not an option, but a professional responsibility. I would emphasize this is true for everyone in the product development process—yes, even the technical writer, if not especially the technical writer.

In any case, this confluence of tweets and posts and other tidbits all lined up in front of me to inspire my theme for 2015: consider that one person. The Eric Meyer. The Bobbi Duncan. To continue to think of the majority–after all they are the target demo–but also not to ignore the individual people in the process, regardless into which demographic segment they fall.

Archives

Blogroll

Connect

About the photo

This is a brown pelican that I watched while visiting the beach at Hilton Head Island, S.C. in Summer 2016. Pelicans fascinate me and I can't help but think that they enjoy gliding over the waves at least as much as i enjoy watching them.

For the photo geeks, I took this photo on June 19, 2016 using a Nikon 200-500 f5.6 zoom lens at 420mm at 1/1250 sec on my Nikon D7000 camera. The image was cooled down in Lightroom to give it a bluer-than-natural look for this web site.