Steven Jong

One of today’s hottest technical trends is the Internet of Things (IoT). The idea is to network together physical objects containing electronics, software, and sensors on the Internet so they can collect and exchange data, offering improved efficiency, accuracy, and economic benefit. Each “thing” is uniquely identifiable through its embedded computing system (that is, by its MAC address), and can interoperate within the existing Internet infrastructure. Experts predict nearly 50 billion objects will be online within five years. The possibilities seem endless (here is a good rundown) and, frankly, a little bewildering.

My former colleague Wynn Grubbs, now senior vice president of business and partner development at PlumChoice, recently posted an article reporting that consumers “struggle to use common connected devices.” Talk about bewildering! Fully two thirds of consumers are “confounded” trying to install or use their purchases. When they need help, half the time consumers only ask friends and family; of those who turn to technical support, 80% are dissatisfied with the experience. Nor is the problem confined to older consumers: 60% of Millennials, the vaunted generation that literally grew up with computers, struggle with their own smart devices. (There is no mention of anyone turning to documentation.) One seventh of consumers eventually return their purchases.

That return rate (14%) is almost triple the return rate of consumer electronics in general, which is already too high. As I previously discussed, Accenture found that customers return 5% of consumer electronic devices because they “don’t work,” even though 95% of the devices returned actually work perfectly. Support, replacement, and restocking costs all reduce the profit margin, not to mention the cost of dissatisfied customers, who rarely come back. Returning items that work correctly is an expensive irony.

Now, the first generation of programmable devices featured unique hardware interfaces, and consumer acceptance was hit or miss. For example, I figured out how to use the brass springs and stops on my lawn sprinklers to water my grass but not my windows, but I know people who just let theirs spin. Smart devices are obviously much more complex and sophisticated than their “dumb” ancestors, with more functions but also more failure modes. The manufacturers’ instincts are to cram as many “smart” behaviors in as possible to justify the cost. A “smart” lawn sprinkler might be able to sense the actual rainfall and the state of dryness of your lawn, saving water and money by watering only when your lawn needs it (and sparing you the effort of going out and turning it on). Perhaps it can avoid watering at night, get the weather forecast from the Web, or use your community’s website to avoid watering during mandatory conservation days. There is probably an app that goes with it, so you can water the lawn from wherever you are. And perhaps it even has voice recognition, so if you say “the grass looks dead” (or “get off my lawn!”) it turns on. But such a device might fail to work altogether if the moisture sensor fails, if it can’t maintain a Wi-Fi connection, if the battery runs out, if a software update fails to install correctly, if the sprinkler’s CPU crashes, if the app fails, if you forget your account password, if it can’t make out what you’re saying, or even if the system is, however improbably, hacked. (Not to mention that running over it with the lawn mower just got a lot more expensive…) In the Internet of Things, where all devices are connected, a brown lawn might require you to buy a better router.

To get consumers to understand how to make sense of their smart devices, manufacturers have tried to make them as simple to use and autonomous as possible. However, this has only hidden their complexity and the potential problems behind a simplified GUI.

Now, understand that Wynn is offering his company’s support services to manufacturers. I wish him good hunting. But we too play the game of helping people successfully understand and use technical devices. (That’s how we make the world a better place.) What can we do? I see both front-end and back-end opportunities in the IoT.

Since the PlumChoice press release mentioned smart thermostats, and since I started my career at a company famous for its thermostats, I’ll take as a case study the Nest Learning Thermostat. (I don’t own a Nest and I’m not suggesting the product has any particular issues; in fact, Nest customer ratings on Amazon are very high.)

Back in the day, the “dumb” thermostat had one sensor and did one thing: turn on the furnace when the room temperature dropped below a set level. Then it learned to do two things: turn on the furnace when the house got cold and the air conditioning when it got hot. The second generation of thermostats was programmable, so that the temperature could be changed at specific times during the day and week: cooler at night to save money in winter, warmer during weekdays in summer while everyone was out. Home heating and cooling is a major component of home costs and energy usage, so if you’re willing and able to program one, a $50 thermostat will still save you money and energy and pay for itself very quickly. Why spring for a connected thermostat, then? The Nest business model is that consumers often can’t figure out, or can’t be bothered to closely program, their programmable thermostats. They’re right. As How-To Geek says in its product review:

You know what we hated the most about our old programmable thermostat? Even if you had memorized the arcane and numerous button combinations required to program the device it still took a significant amount of time to reprogram it which meant you were left standing there in the living room, your arms losing feeling, poking away at it for 15 minutes or longer anytime you wanted to do any significant reprogramming.

Even so, for five times the price, the Nest had better do more than a programmable thermostat. It does. The Nest includes a motion sensor to detect when you’re in the house, and automatically compiles a schedule. It remembers your temperature overrides to learn what temperature you find comfortable. It knows how long it takes your heating and A/C systems to work and takes into account the lag time.

How do consumers learn to use their Nest? From what I can see, the company provides a brief installation guide, important for a product that must be hard-wired into a home electrical system (some consumers pay for certified third-party installation), and only a ten-page “welcome guide” (five pages in English, five in Spanish) that is no more than a marketing pamphlet. The primary information vehicle is the Nest website—and YouTube. For example, here’s a setup video that as of this writing has been viewed 360,000 times on YouTube; I should have such numbers for my work! While I would be comfortable communicating the information in a technical document, the video is more appealing and, I judge, more effective.

Consumers don’t instinctively understand how to use their IoT devices, so the need for technical information still exists, but the delivery media have changed. If your skills run to website content and video, the future look promising. But if your skill set is writing technical manuals, you won’t have much luck working for companies making IoT devices—at least, not on the customer-facing side. Fortunately, there’s someplace else to look.

These sophisticated devices have a back-end Internet interface. Consumers aren’t expected to configure network connections themselves; the devices must make reliable and secure Internet connections on their own. Chris Ciufo neatly summarized the technology and the challenge behind designing smart-device connectivity:

Most of these embedded “wannabe nodes” were created by engineers who’ve never before designed with Wi-Fi. Nor do they understand the hundreds of APIs needed for the most basic TCP/IP connection.

Or: how likely is it that designers have experience with IoT security requiring lock down to protect factory automation or your nanny cam? Forget it; Wi-Fi’s 3AES and the Internet’s TLS/SSL security is more complicated than the whole device itself!

Chris is saying that even the design engineers need help understanding how to get the connections to work. Personally, I like the sound of “hundreds of APIs,” and I think technical documentation has a role to play behind the scenes as well.

So, then, there is a growing market for IoT devices; consumers have ongoing difficulties figuring out how to use them; manufacturers want an inexpensive and effective way to communicate technical information to both consumers and designers; and here we are. I think this makes sense.

In 1986 I was already a veteran computer software technical writer, documenting applications with command-line interfaces on operating systems that were the grandparents, uncles, and aunts of UNIX and then Linux. (One of my colleagues wrote an entire manual for a sort utility—excuse me, the Sort. I tell you, those were heady days.) My division’s software ran on minicomputers, which were smaller than mainframes but still needed machine rooms. (A 20-megabyte removable disk drive was as big as a washing machine.) This was what the word “computer” meant to me.

And then I got my hands on a Macintosh.Continue reading “The Mac Plus User’s Guide, 30 Years Later”

Stephen Pinker, publicizing his book The Sense of Style, kicked up a fuss with his piece “The Source of Bad Writing,” which appeared in the Wall Street Journal last September. He began:

Why is so much writing so bad? Why is it so hard to understand a government form, or an academic article or the instructions for setting up a wireless home network?

The most popular explanation is that opaque prose is a deliberate choice. Bureaucrats insist on gibberish to cover their anatomy. Plaid-clad tech writers get their revenge on the jocks who kicked sand in their faces and the girls who turned them down for dates. Pseudo-intellectuals spout obscure verbiage to hide the fact that they have nothing to say, hoping to bamboozle their audiences with highfalutin gobbledygook.

I resent that remark! I haven’t worn plaid since high school. And we don’t write obscurely to get back at anyone, we write obscurely because we don’t understand what we’re given. But looking past his gratuitous dig at us, Pinker offers the valuable nugget that knowledge itself causes cognitive blindness:

The curse of knowledge is the single best explanation of why good people write bad prose. It simply doesn’t occur to the writer that her readers don’t know what she knows—that they haven’t mastered the argot of her guild, can’t divine the missing steps that seem too obvious to mention, have no way to visualize a scene that to her is as clear as day. And so the writer doesn’t bother to explain the jargon, or spell out the logic, or supply the necessary detail.

Subject-matter experts endemically suffer from this malady. But we can fall victim to it as well, not at first but over time. And sometimes we are carriers. Here’s what I think.

When we start a new project, our lack of knowledge lets us put ourselves in our customers’ shoes, and we clearly see what has to be said. But as we learn more, we lose that advantage. Forgetting to include prerequisite knowledge or steps can make a procedure unusable. At Digital Equipment Corporation, a colleague recounted observing outside a testing lab as volunteers attempted to install printers using his instructions, and wanting to go through the glass to tell them what they were doing wrong. Another company employed a great product manager who was the worst technical trainer I ever saw. He was highly intelligent, knowledgable, experienced, and glib, but he didn’t realize how his knowledge made him a liability in the classroom. Our product was an extremely complex integrated development environment, and I for one never understood the fundamental question of how you decided what piece of code to use to solve a business problem. Neither did our customers. But when they asked him, he would respond, “Well, think about it!” He made customers feel both ignorant and stupid.

To expand on one of Pinker’s examples, I have set up and troubleshot a wireless home network. One configurable router value is NAT filtering, which on my NETGEAR router can be set to Secured or Open. As a user, I naturally wonder: what is it? Why would you secure it, and what happens if you open it? What problems would make you want to change the value? How would you know if it was set incorrectly? The router has a web interface and displays online help for each configuration page, and does a good job explaining the available options: “This option determines how the router deals with inbound traffic. The Secured option provides a secured firewall to protect the PCs on LAN from attacks from the Internet, but it may cause some Internet games, point-to-point applications, or multimedia applications not to work. The Open option, on the other hand, provides a much less secured firewall, while it allows almost all Internet applications to work.” This tells me what my choices are, but doesn’t actually say what NAT is. A Cisco document dedicated to NAT translation, available on the Web, starts with a definition and then continues: “NAT enables private IP internetworks that use nonregistered IP addresses to connect to the Internet. NAT operates on a device, usually connecting two networks, and translates the private (not globally unique) addresses in the internal network into legal addresses before packets are forwarded onto another network. NAT can be configured to advertise to the outside world only one address for the entire network. This ability provides additional security by effectively hiding the entire internal network behind that one address. NAT is also used at the enterprise edge to allow internal users access to the Internet and to allow Internet access to internal devices such as mail servers.” Between the two of them, my questions are answered.

But sometimes it’s not that we learn too much, it’s that we never know. For example, the documentation of forms tends to focus on the mechanics of using the interface, which we understand and can tackle. But what goes in the form fields, and why? Engineers tend to scoff at the idea of providing field information, invariably going to the “are you going to write how to fill in the ‘First Name’ field?” example. But take an example from my current domain. Can you tell me which AVP in an incoming Diameter message to key on? No? Well, think about it: all the supported AVPs are in the drop-down list, and you just have to pick the right one. What’s so hard about that? Oh, I can tell you that I’m talking about attribute-value pairs (information that is true but not helpful). And Diameter is a signaling protocol. And different devices encode different AVPs into Diameter messages. I can go on quite a ways without saying anything useful. (Sometimes I worry I do just that.)

The solution to this problem is to go ask, “what is this and why do I care?” It’s scary to open yourself up and say that you don’t understand something. Perhaps scarier, often the engineers themselves don’t know. A typical response to “what is this value and what does it do?” is “I don’t know, I was just asked to add the value to the list.”

As technical communicators, we are well-versed in the concept of audience analysis, but it never hurts to get a booster shot of naiveté now and again. If you’ve worked on a product for several years, congratulations, but maybe it’s also good to shift assignments once in a while. As soon as you open even a related product’s documentation, the logical holes jump out at you. And you see the problem clearly every time you buy a product for your own use and try to use the documentation. I just switched wireless carriers and got a new phone, and instantly I was transported to when I first got a cell phone and couldn’t figure out how to answer a call. (Actually, I was answering calls and cutting the callers off. My son, who was trying to reach me, could not have been amused.)

Last fall we were preparing for a major vacation, and we bought a Nikon COOLPIX digital camera. It reduced me to helplessness. The designers had overloaded the interface (that is, the few buttons did multiple things each). Even after reading the manual carefully, it took lots of fumbling and practice before I understood how it worked. (The camera has built-in on-display help, which I also consulted a few times.) In the end the camera worked beautifully and took some outstanding indoor and outdoor photos, videos, panoramas, and food close-ups. I think I used every setting except “pet portrait”(!). But I succeeded only because I used the documentation—had I just picked up the camera and tried to use it, I never would have found half the things it could do, and we would have wasted a lot of money and missed some unforgettable shots. Fortunately, the documentation was effective (and the graphics were excellent).

So I guess my vacation was a shot in the arm in more ways than one. It’s good to wipe the knowledge from your eyes every once in a while.