Question your assumptions

I’m the documentation and support team for my company (startup!), which means that I get an interesting, and often valuable, view into the problems our customers are having. Most of them are technical (port numbers), some turn into feature requests, and some are questions about using the product. Those are often tricky, or subtle, and they’re particularly useful to me because they show me where the documentation could use some improvement.

And sometimes the user is having a problem because I screwed up. Let me tell you a story about one of those.

The setup

Our product is a data analysis tool that turns your data into a network of nodes (circles) connected by edges (lines). That’s a massive oversimplification, but the important point is that you can use our software to analyze the network of nodes. One step is to cluster nodes into “groups,” so you can then do further analysis on those smaller groups of nodes. You can also export information, and include group information in that export. So you could create a few groups, select part of your data network, and export that part while including information about which groups the selected nodes belong to.

The problem

A user wanted to do just that. So I pointed him to the documentation that I had written about that workflow. The documentation includes lots of screenshots and links and describes what I saw as a straightforward process.

But the user responded that he didn’t see some of the options mentioned, and the output didn’t include group information.

I ran through the procedure myself, verified that a pop-up dialog no longer appeared, but was able to see information about the groups in my sample network. I brought in two of our data scientists to confirm this: Yup, worked for them. And we verified that the pop-up dialog was removed at some point to streamline the process. Not a big deal, since it just asked a single question (“Do you want to include group information?”) that was now assumed in the process. But they suggested a few things to try: Tell the user to include a limited amount of information to export, and that way the group info won’t get lost in a sea of data.

The user still couldn’t get it to work.

Getting closer to a solution

Ok, time to regroup. What version is he using? What version are we using? Were there any changes that could account for this? Are we SURE that the user is selecting the correct command (because there are two commands that are just a bit too similar, but give different results)? Have the user send us screenshots!

The user provided all of that. There was no obvious problem. Fortunately, he remained patient as I tried to give him a useful answer.

Finally, the solution

And now there was nothing left. Either it was just a fluke, or…

Ok, there was one other option. But it was so silly, so basic, that I felt bad about asking. Remember, the user wanted to export information about his data, including information about the groups that he created.

But there was only possible explanation that remained.

So I asked him: Did you create any groups before you tried to do this?

And the answer was: No, I did not create the groups.

Yes, I facepalmed.

Why it’s my fault

I reviewed the article that I sent to the user. The title involves “exporting group information,” the description describes how this process will export your data, including group information. The steps mention exporting group info (and I need to update one of those to account for the missing pop-up dialog).

But the topic assumes that you have created groups. After all, why else would you want to export information about those groups?

I believe in the main argument in The Design of Everyday Things: It’s not the user’s fault when they don’t understand how to use something. Even though I assumed that it was obvious that you couldn’t export information about something that doesn’t exist, the documentation never clearly listed “create some groups” as a requirement. And for more users, it wasn’t a problem.

But at least one user didn’t understand that, and that led to a support ticket, which resulted in a lot of time spent overthinking possible solutions to what turned out to be a very simple problem.

What I’ve learned

In this case, the documentation failed by not being specific enough. For one thing, I was relying on the topic title, and headings in the topic, to give the user some context. But we already know that readers tend to skim titles and headings, so that was obviously a mistake. But our customers are not reading our documentation at leisure: They’re reading when they’re trying to get something done, and want to get back to their work. So they’re more likely to skim everything, and maybe stop to look at screenshots or a few things in bold.

Our customers might be reading so quickly that they fail to make the connection that before you can export information, you need to be sure that information exists.

What’s worse is that I know this. I’ve seen this before. But I still need to be reminded that even obvious assumptions aren’t obvious to everyone, and that can cause problems that land in someone’s lap. Fortunately, in this case it was my own lap, and I can make sure the technical writer does his job right this time.