Docs by Design - Bob Watson ponders technical writing, API documentation, and the world in general

January 9, 2015January 9, 2015

Knowing your audience

Image of earth from space — Where to find our audience

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.

So many studies. So little time.

January 8, 2015January 8, 2015

These are your users

Getting back to this year’s theme, I see this video pop up from time to time in Twitter feeds and the like.

It’s been linked from this article about the Facebook log in and it reminded me of a recent phone call I had with my mother. It reflects the language barrier we encounter whenever she tries to describe a computer problem she’s having.

While we’re both college educated and speak English as our native languages, that’s of little consolation during these long-distance tech-support calls. In the past, rebooting the computer usually fixed the problem, and masked the underlying language barrier. Recently, however, she got some new network hardware, which was giving her trouble. In no time, it turned into an Abbot and Costello routine as we tried to identify the devices like cable modem, DSL modem, router, etc.

Fortunately, she got it figured out with help from my sister, but it reminded me of how we are not our target users.

Not by a long shot!

January 7, 2015

Well, that was fast, Bob

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.

Four days and counting…

January 6, 2015January 8, 2015

Lost in translation

I’m mixing a some of my favorite themes, music videos that feature dance numbers and technical writing with a dash of Latin culture.

(Bear with me… or skip to the technical part)

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.

Yet another study to put on the list.

January 3, 2015January 13, 2015

My theme for 2015

Statue of Janus, the Roman god of beginnings and transitions. — 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.

Which spawned a burst of articles like:

The problem with Facebook’s “Year in Review”

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.

Nobody said it would be easy, but that’s what keeps it interesting.

December 31, 2014November 29, 2015

A new year. A new blog.

I’ve been contemplating a blog for quite a while. Why start now? Well, I’m starting this year with a long list of writing projects so what better way to procrastinate then having a blog that will constantly be begging for content?

Like this photo of a house from my childhood, this blog is under construction, so expect to constantly grow and improve. Like an agile development project, even though it’s not finished, it will always be usable–and, with any luck, more useful with every revision.

OK, that’s enough similes for now. A happy and prosperous 2015 to all!

More about me.