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?