Customer's Language Redux

I've talked here before about speaking the customer's language. Yesterday I saw a post from another technical writing blog that reinforces this point. I quote:

===
 ....[A] user may want to send a letter to many different people. If the user doesn't know about the mail merge feature, they will insanely copy and paste all the letters.


Having an index entry of mail merge is useless, because if the user doesn't about this feature, they can't look it up! However, having these index entries could help:

• distributing a letter to many recipients
• letters, sending a letter to many recipients
• mailing a letter to many recipients
• mass mailings, sending
• recipients, sending a letter to
• same letter, sending to many recipients
• sending a letter to many recipients

Yes, these are long index entries, but so what? A good index attempts to anticipate all the strange and wonderful ways a user might look up a topic.


The mail merge topic itself has to clearly explain why doing a mail merge is better than copying and pasting, because if the user cannot see the benefit of what you are suggesting, they won't do it.

===

"strange and wonderful" ... exactly :-)

I Don't Want You to Think

No, really, I don't! At least, not when reading my documentation.

One of my guiding principles behind writing & reviewing technical documentation is "Remove the burden of thought from the customer." After all, our customers are NOT getting paid to read documentation. They're not even getting paid to figure out how to program in LabVIEW. They are getting paid to solve problems.

So when I'm writing or reviewing technical documentation, I think to myself: how hard would a customer have to think in order to decipher this documentation? Hopefully the answer is "not very hard" because time spent deciphering the documentation is time not spent curing cancer, controlling photon beams, developing alternative-fuel technologies, monitoring structural health, and so on. But if that's not the answer I get when I look at the documentation, I have a number of ways to bring the effort level down.

• Speak your language. This one is difficult to do because the first people to define terms are the engineers who write a feature specification. As such, they define the language implicitly when talking about their feature, so because we use those specs as basis for documentation, we often repeat their language and incorporate it into headings. But we shouldn't. Compare "Using the Throughput Control" with "Achieving High Throughput". Which heading are you more likely to notice? I'd bet it's the one that speaks more to the task you want to do than the feature we are providing.
• Use pictures for visual products (like LabVIEW). Pictures improve a reader's ability to scan the text instead of requiring them to read a bunch of steps, provide anchors on the page that serve as reference points when switching back and forth between windows, and make the help look more colorful and less intimidating.
• Provide examples. Examples tell stories that can match your application, so you're more likely to notice  and understand the explanation in that form. Examples also are the difference between high-level, theoretical statements like "Use the Blah API to optimize throughput when transferring data" and more low-level, specific statements, like "For example, if you are monitoring the temperature on a wireless node over a network, the BLAH API increases throughput significantly compared to the BLAH2 API. Here's why ...."
• Answer questions up front. If the LabVIEW API provides you two different ways of doing the same thing (and very often we provide more than two ways), you shouldn't have to wonder when to use a particular option. We should tell you. This issue is particularly helpful in the FPGA realm, where placing a checkmark in a single checkbox can have large timing consequences when it comes time to translate your design into hardware. At the very least, the documentation should make you aware of the trade-offs in checking that box vs. not checking that box.
• Be consistent - You'd be surprised at the amount of effort that goes into ensuring consistency among terms like "PC", "computer", "system", "machine", "console", "host", "target", "execution target", "remote execution target", and so on. This issue crops up even more in the FPGA/RT realm where you have one or more host computers connected via network to remote, embedded PXI or cRIO chassis. What the heck do you call all these things? And we still have a ways to go.
  
  (Five points to anyone who noticed the inconsistency in how I punctuated this bullet item compared to the previous ones.)
• Provide direction. At no point should you ever be wondering "What do I do next?" As Al talked about, technical writers have a number of ways in which to provide direction, both visual and textual.

These are just a few ways in which we can reduce your time spent thinking about the documentation and get you back to your task at hand. Unfortunately our ability to excel at these tasks are limited by two rather large factors:

• Lack of knowledge about what customers do, how they think, and what they want to see in documentation. This is a particular problem in the technical communications department where we have even less access to customers than general R&D. Click those feedback links, folks!! They are at the bottom of every help topic LabVIEW ships, and also for some other products:
  
  We receive every piece of feedback and review it, even if we can't always act on it because ...
• We're a for-profit company with deadlines. That's the nature of the biz, folks -- we have to ship a product on a given date and we can't always take the time to be 100% perfect in our documentation. But we can keep trying.

This post was inspired by not only thoughts I've had for the past few years, but also a post I saw about a restaurant removing the burden of thought from its customers by providing pre-calculated tips (15%, 18%, and 20%) at the bottom of each bill. The author (a tech writer) writes:

This document saves the user the grief of having to manually calculate the tip. It considers the needs of the user and immediately fulfills them, like any great document should.

Exactly, man. Exactly. Instead of making tip-calculating a chore ("Let's see, divide by ten ... move the decimal over ... now multiply again by the bill amount ... wait .. where's my cell phone calculator?!") the pre-calculated tip removes the burden of thought from the customer, thus reducing the pain of this task (and reminding them to do it at the same time), thus lowering the barrier to doing the task, thus making it more likely that the customers will complete the task (in a satisfactory manner and with a minimum of pain).

Of course there are societal norms around tipping that make it likely to be done anyway, but again, the point here is that the documentation removes the burden of thought and, in doing so, actively aids the user in completing the task.

Genius. We should be so lucky to have documentation that is so comprehensive and user-focused.

Speaking the Customer's Language

Small bit of background: I recently got (more) into digital photography and have been having a fun time dreaming of buying fancy-schmancy camera lenses. So I was checking out Sigma's web site and saw they have an "advisor tool". I clicked it and was presented with this:

This tool is of absolutely no use to me. Why? Because I don't think in terms of "Lens technology" or even "Weight". I think in terms of "I want to take awesome pictures of bands at concerts without having to wander through the mosh pit." or "I want to take awesome pictures of friends at house parties where I'm typically like 3-4 feet from my subject". Those are the first things I think about. Not whether I want "APO" or "DG" (whatever the heck those mean) technology, or whether my lens needs 7 or 12 groups, or even weight. Weight's definitely a factor, but that only helps me filter down my choices. It's not where I want to start out.

Here's my thought: pro/advanced customers will not use this advisor because they already know what lens they want to buy; they can just Google it to find more info, a review, or a price. They think in terms of "Okay, I need a lens that hits 200mm at f5.6." They don't need a wizard for that; they've got Google or their local photography store. And if they did need a advisor for that (to find out what Sigma offers in those categories), this one certainly won't do the trick.

The advisor's geared more towards beginners and semi-beginners like me who don't even know what's out there to match their needs, and we certainly aren't experts at terminologies like focal length and aperture size. And if that's the case, then this wizard doesn't speak our language, which means using it will frustrate me, and I'm more likely to try my hand at discussion forums or asking a friend, any of which might lead me away from Sigma.

I had a similar camera-related issue a few weeks ago. Setup: I know there's some camera-flash mode out there where you can fire the flash at the endof an exposure, rather than at the beginning. I have heard this is called "rear-curtain sync". I looked through my Canon Rebel XSi's manual for this term but did not find it, so I assumed that the built-in flash does not have this capability.

Wrong. It does. It turns out that Canon calls this capability "second-curtain sync". Why? No idea; perhaps they want to be distinct from Nikon and/or other camera manufacturers. But since I didn't know how Canon thought of it, I didn't know what terms to search for. So I didn't find the information I was looking for. Maybe this is beneficial to Canon because they can sell upgrades (Speedlite add-ons) easier if customers think their built-in flash doesn't perform as well. I really hope that's not the case, but you never know :-)

This issue comes into play in documentation. You have to think like a user and talk like them also. If you do that, search hits will come up and index entries will be informative, and users will find the information that they're looking for. And that's what we all want :-) This is especially true of topic headings, which are displayed more prominently in topics. That's why I named this topic the way I did. I called it "Specifying the State in a Region that Executes First" because I imagined that would be the question the user has in their mind: "I have a state in a region; now how do I make sure that this state executes first?"

I could have called it "Using the Initial Pseudostate" and been done with it. But who the heck knows, out of the box, what an Initial pseudostate is? (Outside of the development team, I mean.) I feel that because I used a task-based heading, users are more able to find the information they're looking for. It's not always easy and it doesn't always work, but I feel that results in higher-quality documentation and a more positive experience for customers.

What products or help files have you run across that speak your language?

These Sentences Confuse Me

From ESPN:

Jamie Moyer allowed seven baserunners before recording an out in the third inning. Somehow, none of them scored.

I read this bit and did a double-take. This makes it sound like Moyer did the following:

• Allowed seven baserunners in the third inning
• Did not record an out until the eighth batter of the inning
  
• Did not give up a run during this time
  

If you follow baseball, you might remember there are four bases. You can allow a maximum of three baserunners before the next one drives in a run. So to allow seven runners in one inning before recording an out and not allowing a run seems pretty impossible to do.

Moyer's good, but he's not that good.

(Baseball Terminology 101: We say "allowed baserunners" instead of "allowed hits" here because not all of the runners reached base on hits. The article mentions that Moyer allowed six hits in the night, so if he allowed seven baserunniners, one runner reached base on an error or a walk, neither of which count as a "hit". But you still get on base. Baseball sure does split hairs a lot.)

Continuing to read the article you'll find out that Moyer allowed two baserunners in the first inning, three in the second, and two in the third -- total of seven allowed, now -- and none of them scored. Oh, that's what the article meant -- not seven baserunners in the third inning, as implied, but seven baserunners through two and a third innings. And none of them scored.

(Baseball Terminology 101, #2: Recording one out counts as "a third" of an inning, since there are three outs per inning. So "two and a third innings" means Moyer pitched two innings and recorded one out in the third inning. And when we say "inning" here, we really mean "half an inning", since technically an inning consists of a top and bottom half, and the pitcher only pitches one of those halves. Still with me?)

So Moyer really did the following:

• Allowed seven baserunners through two and a third innings
  
• Got the requisite six outs over the first two innings (this is implied by the first bullet above, but I thought it better to state explicitly here)
  
• Did not give up a run during this time
  

Were I editing this article, I would suggest that the statements above read something like:

Jamie Moyer allowed seven baserunners through his first two and a third innings. Somehow, none of them scored.

Much clearer, I think.

Asking Questions is Key

I think one of the hardest things in technical writing, especially for new hires, is to be assigned to document a product or feature that you know nothing about. Since we have a wide variety of LabVIEW products, from signal processing to HMI to control and simulation to report generation to sound and vibration measurements (not to mention the core product itself), no one can be expected to understand the minutiae of them all. And yet our writer who works on a Control Design product might be asked to edit another writer who is working for an HMI product. Or the signal processing writer might leave and the HMI writer might be asked to fill in until we can find a replacement.

Whew. That's a lot of stuff to cover. But we're not engineers. Some of us have a technical/mathematical/scientific background, sure, but many of us are English or Tech Comm majors. How do you write help for a product you know nothing about?

Well the answer is: you learn. You do this primarily by working with Subject Matter Experts (SMEs) who, here, are the engineers who develop these products. They are the ones who have not only the domain expertise (like advanced degrees in the aforementioned disciplines), but also the LabVIEW programming knowledge to help you write documentation.

Still, it can be daunting to read a feature spec and not know where to begin. That's why I believe one of the most important skills a technical writer can have is knowing how to ask questions. (There's a reason we have several Journalism majors who work here.) Questions about functionality, background reasoning, implementation, usefulness, future features, and so on. Questions that nitpick and dig into what the developer really meant when he said "if necessary". These are all fair game in determining a starting point, an outline, for writing documentation. And once you have that outline, you're in far better shape than you were before, because you have a plan of attack. Even if you initially knew nothing about the feature.

Of course, it's a chicken-and-egg problem. You can't ask questions if you don't know enough about the feature to know what questions to ask! That's why, on the LV Doc team, we've developed a list of questions to help writers, especially new ones, get started writing about unfamiliar features. That's why research with the developers can be so valuable. Even if you don't know what they're talking about, you can pick out patterns, keywords, and things to ask questions about later.

That's why we look for writers who are geeks, who love learning technical information. We don't ask you to be a computer scientist when you join NI. But if you're going to write for (as an example) LabVIEW, you'd better get a thrill out of learning about object-oriented programming, data types, and 3D graphs. Otherwise you're going to hate it here, which is a situation nobody wants :-)

Over time you develop patterns of behavior that proves successful in giving you a sufficient amount of information about a product in a short amount of time. And then when you're asked to pitch in on another product, you aren't afraid anymore. You trust yourself to be able to obtain the knowledge you need in order to do your job well.