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

March 17, 2015

How many topics in a page?

API reference topic type distribution observed in study of open-source API documentation

This question has come up a few times recently and the answer, like the answer to so many technical writing questions is, “it depends,” of course. Which begs the next question, “depends on what?”

Well, at the root, what the reader wants to accomplish, perhaps most critically, how do they want to accomplish it.

I researched this a couple of years ago and found the multi-topic/page format was used in the API reference documentation we studied to be twice as common as the the single-topic/page format.

Graph of API reference topic type by API size — The distribution of API reference topic type by API size

Now, because a format is more popular doesn’t necessarily mean that it’s better. Looking at this chart from the study shows that the format preference shifts towards the single-element per page format with larger APIs. It’s possible that the difference observed is nothing more than an artifact of authoring systems or organizational style guides.

Research on how people construct knowledge, however, tends to prefer the multi-topic/page format (to a point). If you are constructing knowledge about an API, you might look for an overview, some sample code, some explanations of some key methods, go back to the overview, look at some more sample code… Lather, rinse, repeat. Such a learning method is best facilitated by a big topic in which the reader can skip around to see quickly all the related information in whatever order his or her learning style desires. Doing that with each topic in a separate page requires multiple web-server accesses, each interrupting the flow for more time than in-page navigation. While the 2-3 seconds it might take for the page to load doesn’t sound like much, if it breaks the reader’s flow, it degrades the learning experience.

A key part of this learning method is the intra-page navigation–to facilitate meaningful skipping around, or random access to an otherwise sequentially oriented topic. This topic came up in a discussion about the scrollspy feature of Twitter Bootstrap, which provides some very helpful in-page navigation elements. The advantage of scrollspy is that it builds the in-page navigation when the page loads, which makes it much easier for the author (and maintainer) of the topic.

March 16, 2015March 17, 2015

Back from Honduras

The field hospital in Rus Rus, Gracias a DIos, Honduras

I’m finally getting back online after being in Honduras for two weeks and then spending the next two weeks catching up to the life I left behind.

For the last two weeks of February, my wife and I were in Honduras working as members of a brigada medica (medical brigade) with the International Health Organization of Minnesota (IHS of MN). We worked as a part of a medical & dental team—my wife was an interpreter and I was a radio operator. The organization deployed eight teams to various parts of Honduras. Our team went to a field hospital in Rus Rus, a small village in the jungle, 60-some miles inland from the Caribbean coast of Honduras and just five miles north of Nicaragua in La Mosquitia.

IHS of MN has brought medical brigades to Honduras for 33 years. This was our second trip with them and our second time at the field hospital in Rus Rus. Last year, I filled in as an interpreter for the medical staff when I wasn’t on the radio. This year, we had a surplus of interpreters, so when I wasn’t working the radio, I mingled with the local people who came to visit the clinic and got to know more about them and their lives.

As with our trip, last year, it was an amazing experience. We had the pleasure to work on a dedicated team of volunteers who provided health and dental care to people who would otherwise not have access to these services.

More stories, photos, and videos to come!

February 4, 2015February 5, 2015

Lies, damn lies, and statistics

Chart of science-public split on science-related issues (from fivethirtyeight.com) — Science-public split on science-related issues (from fivethirtyeight.com)

The headline from stats web site, http://fivethirtyeight.com/, says Americans And Scientists Agree More On Vaccines Than On Other Hot Button Issues while the headline from Mother Jones, reporting on the same data, says, This Chart Shows That Americans Are Way Out of Step With Scientists on Pretty Much Everything. You wouldn’t know from the headlines that they were reporting from the same data.

If you ignore the text and just look at the data in each chart, while the chart from http://fivethirtyeight.com/ breaks the data out by political-party affiliation, the numbers do appear to be the same (or the same enough). The rhetoric and visualizations, however, are quite different.

Things that make you go, “hmmmm…..”

Or, another way to look at it is that it always pays to go to the source data.

Chart showing opinion differences between public and scientists from Mother Jones — Opinion differences between public and scientists from Mother Jones

February 3, 2015February 4, 2015

A great tutorial saved my glasses

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.

Thanks danliv99!

January 31, 2015January 31, 2015

Too little, too late

ATT's quick reply to a recent tweet — ATT’s quick reply to a recent tweet

I have to say that I was impressed by ATT’s response to a not-so-complimentary tweet I made last night. While ATT replied 12 minutes after my tweet, the conversation took place three months too late.

I bought my first cell phone in 1992 as a Cellular One customer– back when the phone was the size (and weight) of a brick. I stayed the course through several mergers and 20+ years of technological evolution. But last fall, I’d had enough. What was the last straw?

Their web site

Last fall, I was ready to upgrade my aging iPhone 4 and, like so many others, started my research on the web. As a loyal ATT customer, I started with their site. In fact, I went 80% of the way through the upgrade process several times before I would end up hopelessly confused. The site broke a cardinal:

A web site should never make the customer feel stupid.

Each attempt to make a purchase sent me into a Gordian knot of screens, warnings, seemingly endless and contradictory terms and conditions, to the point I wasn’t sure what I was going to end up paying or getting. Each time, I started out knowing what I wanted (a family plan and a new iPhone), but by the time I bailed out, I wasn’t sure which end was up. I’m sure I’m not the first to say it but,

Why can’t comparing cell phones and plans be easy?

Do customers actually write in and say, “Could you please make your site and terms more complicated? I’m afraid that I almost understand them?” Honestly, I’ve had an easier time navigating a hall of mirrors. I’m not going to publish a heuristic evaluation or usability report (although they can hire me to do that, if they’d like), but as a customer,

I felt like the ATT site had talked me out of being a customer with each interaction.

So, after several frustrating attempts, I finally went shopping and ended up moving the family to T-Mobile. While that was an experience for another blog post, I’m glad to have put it all behind me.

I’m impressed to see they have responsive and proactive customer service agents, and a 12-minute response to a tweet is pretty impressive. If their web site had been as helpful, I might still be their customer.

What can they do?

After all this, it seems only fair that I offer some constructive criticism (if not the entire usability report).

Describe features in customer terms, not industry jargon. The catchy plan names need to be followed quickly by descriptions in plain English.
Prices. Just tell me, please. Don’t make me work so hard to become your customer.
Make the plans easy to compare. Apples to apples, please.

So, I’m glad I’ll not in the market for a cell phone in the near future. With any luck, the next time I am, things will have improved.

January 30, 2015

In-flight reading

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.

Back to the paper.

January 30, 2015January 30, 2015

Colombia has 11 of the top 100 universities in Latin America

photo of The University of the Andes from El Pais. — The University of the Andes (la Universidad de Los Andes Colombia) – number 5 in this year’s top 100 universities in Latin America

From El Pais (in spanish) Once universidades colombianas entre las 100 mejores de América Latina.

Eleven Colombian universities rated in the top 100 universities of Latin America according to Quacquarelli Symonds, who rates the universities around the world. Here’s the entire list of the top 100 universities in Latin America for 2014 from their site. The Pontificia Universidad Católica de Chile won the number 1 spot this year.

January 17, 2015January 17, 2015

Keeping the design user-centered

Link to presentation — Watch the video of the presentation

This quarter’s speaker series in HCDE (the University of Washington’s department of Human-Centered Design & Engineering) is off to a great start with Paul Elrif’s presentation titled, Please Stop Working on UX No One Really Needs.

Paul presents some examples of UX design gone astray and how UX designers and researchers can help keep it on track.

A key takeaway to ponder from the talk:

“People/teams behave in the way they are rewarded.”

When you know how [the] people [in the room] are rewarded, you’ll know how to reach them. Unfortunately, he says, that too often teams are rewarded for shipping more than for meeting the customers’ requirements.

It’s too bad that he had only 45 minutes because he was just getting to the ‘good part’–what to do about it.

Maybe in his next installment?

January 15, 2015

User research to the rescue!

As Hannibal of the A-Team would say, “I love it when a plan comes together!”

I responded to this post in Quora from someone asking for advice on how to improve their website. There was lots of good, 1st-person, advice when I read it, so I suggested that they go to their target demographic ask them what they thought.

Have you tried usability testing it with some people from your target market? E.g. go to a local university with this [home page image] on a tablet, or even just a photo on a clipboard, and ask people a few questions:

a) What does this page inspire you to do? Tell me more about that. (after each question)
b) Where would you click?
c) What would you expect to find after you clicked?
d) Would you sign up for this? Why/why not?
e) What does “verified” mean to you?
f) Thank you! here’s a gift card for a coffee.

If you started after breakfast, I would imagine you’d have a much better sense of what you need to improve by lunch time.

(Read Quote of Bob Watson’s answer to What things can I improve on this home page? on Quora)

Later, I read this comment to the post.

Bob, I actually did usability testing today as you advised and got some real feedback from students. It really helped in understanding what would resonate with students.

I also want to do A/B testing to see which messaging converts better. Do you happen to know any resource (website)?

Thanks a lot for your feedback

Happy to help!

January 13, 2015January 13, 2015

Reducing life events to a checkbox

This tweet came to me today, linking this blog post about personal histories and how a simple question on a form can a much more profound impact on the person filling out the form than the form designers might have imagined.

Is there such a thing as a simple question anymore?

How many kids do I have?
How long have I been married?
Where am I from?

I can appreciate her point of view.

These questions might look easy to some, but for me, each one is a blog post in itself.

On the 13th day of my theme for the year, it’s getting more interesting by the minute.