A manual I wrote in the 1990s. The equipment is displayed in the Computer History Museum (talk about feeling like a fossil).
I’ve had many technology tribulations, even though I was a freelance technical writer for about 15 years, in parallel with my work in marketing writing. My bonus grandson had to help transfer photos from my cell phone to my computer (it really wasn’t that simple). I’ve experienced hard drive failures, viruses, and strange issues with laptop batteries. One power problem turned out to be caused by my housecleaner inadvertently pulling the computer’s power supply out of the outlet, which I hadn’t noticed. Rule 1 from “Famous Tech Writer’s School”: always check to be sure it’s plugged in.
... the engineers asked, "What did you do? How could you possibly break the program?"
The good news is that, faced with a problem, I usually know what I don’t know, what is safe to try to fix, and when to throw in the towel. That said, I’m of our generation, for sure. Just today I read about an air fryer that is cloud connected and controlled by a cell phone app that can be hacked, such that all the computers and devices on the home network can be compromised. Seriously, who needs a cell phone app to control an air fryer?
Tech Writing Losses and Wins
As a technical writer, I gained a lot of exposure to the development of new hardware and software products as I wrote instructions about how to use them. Technical writing is one of the hardest jobs I’ve ever done, which is why I eventually gave it up. The process demands accuracy under very tight deadlines with quickly evolving products. Worse, tech writers don’t really have a place in most company structures, so no one wants us in their group. Software engineers in particular tend to view us as intellectual inferiors.
When writing, I saw myself as a first-time user without a background in what I was writing about, so that I could help the user. Product developers, particularly software engineers, tend to assume a lot of knowledge. We’ve all been baffled by terrible instructions, a major technology tribulation. One of the funniest videos I’ve ever seen was in a tech writing seminar in the 1980s, showing two hapless women attempting to insert a floppy disk into a drive using a procedure that engineers wrote. The women failed.
Software engineers, typically not known for their modesty, can be in denial of possible errors and bugs. Much of my technical writing job, besides the critical work of figuring out how to organize and present the information in an understandable way, was using software as it was developed, so I inevitably found problems. At long-time clients, I gained a reputation (good or bad depending) for finding bugs and causing software to crash.
Once I was writing instructions for how to use a software-driven robotic conveyer belt that transferred blood sample tubes to analysis equipment. The engineers, who had known me for a while, smirked and told me that the software was so robust I couldn’t break it. Ten minutes later, I crashed it. Exasperated, the engineers asked, “What did you do? How could you possibly break the program?” When I explained the sequence, they responded, “Nobody would do that.” I replied, “Well, I did it, so your customer might. Better I do it now than your customer in the field.” I was relieved when this product development project was canceled.
Technology can change in arbitrary ways. One of my favorite technical writing projects in the early 1990s was for the famous Xerox Palo Alto Research Center. The resulting manual is my featured image. One of the teams there developed an electronic white board, on which groups in remote locations could dial in by modem and share documents in what is now a very rudimentary way. Operating the system required large white boards at every location, and special pens to write a series of instructions on the board using special gestures.
The cognitive psychologists and software experts invented gestures and developed a written language with them. I learned a lot about users and software and had a great time describing the gestures and coming up with fun and interesting tutorial examples. It probably was the best quality manual I ever wrote. The product was launched, but within a few months, the worldwide web became a reality, and the board and its language were immediately obsolete.
Help in the 21st Century
Something fundamentally changed in the early 2000s as younger generations emerged “digitally native.” Instruction manuals began to become rare as technology supposedly became easier to use, to be replaced by digital help systems. In theory, I can understand why–cost, greater availability of computers and phones, and more people familiar with technology. Alas, many of those help systems aren’t much help, because it’s not easy to find the exact procedures needed to do something. Rule 2 from Famous Tech Writer’s School: if the product’s help system doesn’t solve the problem, trying Googling the issue, especially for those maddening error codes.
On the familiarity and ease of use issues, some might ask, who needs a manual for an oven or dishwasher? After all, we don’t need to learn gestures to use these appliances. Except, products now have so many features, whether we want them or not, that they can be frustrating to understand. When my mother moved into an apartment in a senior residence, we had to set up the software in her new oven, loaded with features, most of which she would never use. After 45 minutes of strenuous tinkering, I finally set the date and time, without which the oven wouldn’t operate at all. After another 30 minutes, I figured out how to turn the thing on. So much for simplicity.
Some software development practices are improving. Many companies now have “UX” functions, with user experience specialists who set standards and test products on real users. Results are mixed. Technology can be great, but despite the best intentions, tribulations will be with us.
For detailed and very interesting insights about why high-tech products drive us crazy, have a look at The Inmates are Running the Asylum by Alan Cooper. Although the book is 20 years old, its explanations ring true today.
MarianI have recently retired from a marketing and technical writing and editing career and am thoroughly enjoying writing for myself and others.
Marian, your first rule is so true. It has happened to us enough times that, before we call for help, we check the plugs and then unplug and reboot. I wish we had someone like you writing the directions for all of our devises. The worst are the ones with just pictures. I can’t follow those at all. I suspect part of the problem with written manuals these days is that they are poorly translated from another language.
You are right, Laurie, good translations take time and money, so many firms don’t do it. Sometimes I will edit translated manuals to make them better. Hooray for those companies.
Great story, told from an insider, Marian. When John Z was setting up Retrospect, he wanted some technophobe like me to test it out, figuring that if I could use it, then it was simple enough for general use, similar to you, writing the tech instructions and finding the bugs. I am sure it was very difficult to have to make sense of the product, write it up in a user-friendly way, then find the flaws. Truly heavy lifting.
Your description of setting up your mother’s new oven is terrifying. I guess it has been a long time since we’ve bought appliances and none of them are “smart” (an air fryer controlled by a smart phone?). Really beyond the pale.
Betsy, can you imagine a 93-year-old woman trying to set up that oven? Really crazy. I’m worried about buying new appliances, and within the next year or two I’ll need a new car. It will take a while to get used to all that new technology.
Thanks for sharing the tech writing experience–it was very clear! I have also served as the average person testing out electronic medical records, and tried to give feedback. There seemed to be a combination of removing “nonessential” prompts and adding multiple features, causing , general confusion. I mean, when they add three dots to the corner, and a tiny arrow, everyone KNOWS that is a menu and you can right click. And if you just press “enter”, the thing you want will appear, or disappear. Seems that if everything were designed so it functioned perfectly well at a basic level, 90% of people would be happy with that; the other 10% could open the magic back door to all the bells and whistles.
Completely agree, Khati. There is a phenomenon in the tech world called “Featuritis” or “Christmas Tree Syndrome.” Software developers and hardware engineers, either interested in leaving their mark (ornament on a Christmas tree) or proving that they are really busy, add bells and whistles. It’s probably more fun for them, but not for the poor user. At one client a colleague and I were tasked to do research to see what customers were complaining about in a hematology analyzer system. It turned out that the instrument was difficult to clean, and a combination of hardware redesign and some automated cleaning routines would really help. We presented our results, but the engineers ignored them because what we uncovered wasn’t glamorous or interesting to them, even though customers would have been delighted by some updates. How sad.
Thank you, Marian. As Betsy noted, it is great to get this story told from the standpoint of a tech insider. And, better yet, from one who realizes that most of us are (desperate) outsiders. You are a rarity, I’m afraid.
Two of your points particularly resonated with me. First was the “Is it plugged in?” one. Funny how often that is the case. The second is wonderment over the need for so many “smart” appliances. Do they just do that because they can — even if poorly — or is there some real advantage to it? I ask that with some trepidation because, years ago, I recall thinking that the idea of cameras in phones was stupid and would never catch on.
A lot of times I’m afraid designers do things because they can. My washing machine plays a tune when the cycle is complete. Harmless and benign, but not necessary. I tend to trust, not technical folks, but people with a liberal arts slant, like the late Steve Jobs. I think they have a finger on the pulse of what really is smart for customers.
Love this story from the point of view of a technical writer, Marian! Your anecdote about the engineers saying “Nobody would do that” is perfect. And of course the answer is that if you did, somebody else certainly would. How fun that you had a reputation for finding bugs and causing software to crash.
I’m sure the instruction manuals you have written are so much better than what we usually get. I have to say though, that our new dishwasher came with excellent instructions, so that was a relief! Can’t believe how complicated your mother’s oven was.
I have noticed that some consumer manuals have improved, Suzy, and I’m glad your dishwasher docs were good. Japanese and Korean companies have made great strides either with translation or with having them written by professional tech writers in English. The Chinese have a way to go.
My dishwasher is a Miele, which is a German company. Maybe they have a better grasp of English.
The Germans do have a better grasp of English, Suzy (German is a lot closer to English than Chinese). Also, although it’s a stereotype, I have found that Germans tend to have organized minds, which helps in writing instructions.
Ah yes Marian, more than once a repairman I had called told me patiently, “Madam, first you must plug it in!”
The rest of your tale of tech tribulation I must say is Greek to me!
That’s OK, Dana, it’s better to keep life simple if at all possible.
Thanx Marian, reading all these tech stories I was starting to feel like a dinosaur!
As my now retired from tech friend has said: simple is hard. Maybe that explains the bells and whistles complex. Very interesting inside look at the language of tech! Another friend has stories about when tech folks needed to invent the language usage we now use without thinking: icons, menus, cursors, links, mouse, clicks, etc.
Agree, Risa, it’s hard to make things simple. Did you know that we use bug because years ago a real bug caused a computer to short out?
Wonderful insights, Mare…you’re my shero!
Re your Rule 2, in terms of just about anything, I’m more apt to Google my question or problem than go directly to any guide or help page…it’s just faster. As you know, more often than not, all I have to do is type maybe four and a half words and up pops my issue, then I just go from there. Not only are there numerous articles, there’s usually at least one video. Although some of them are no help at all and it makes you wonder why they bothered.
How true, Barb, Google is usually much faster than guides or help. Sometimes you have to know enough to understand if the person knows what they are talking about, or whether what they suggest is really too advanced or too risky for your skill set. When I first was selecting a smart phone to buy I did look at some demo videos, and they actually were informative.
A tour de force, Marian. I marvel at the ability of those like you who can master technical writing. Brava.
Thanks, Tom. Despite a grain of truth in Dilbert’s “Tina the brittle technical writer” character, it takes an unusual combination of skills and personality to be a good tech writer. I am amazed that some of my colleagues can still do it so well.
One of the conference rooms in my Unversity department still has an electronic white board. It was in use less than a year. Now it just serves as an old-fashioned dry-erase board.
Not at all surprised, Dave. A lot of electronic equipment has ended up as doorstops.
Marian, I’m struck by how complementary our accounts are, with me telling how a non-computer scientist got into tech writing and you telling what happened when you got there. In fact, I could almost have written yours — though I’m glad you did since you told your stories so well. I too was the first user of many software and hardware products, finding bugs that the engineers believed couldn’t happen, and I too documented a gesture-based system, in my case a pen-operated notebook computer that we tried to produce only about 15 years before it became technologically possible.
When I was a columnist for InfoWorld, I asked readers to submit their own experiences with unclear, incorrect, or nonsensical manuals. One memorable one was an early Apple manual that had a lengthy paragraph about unpacking the equipment and setting it up, culminating in an instruction to open the last internal box … “and there you will find this manual.” Classic!
I have to say, though, we love our musical washing machine. How else would we know the cycle is done without trudging into the laundry room?
Timing is everything in technology, John, and I guess our pen-based systems were either too early or too late! I smiled to know that even Apple makes mistakes in manuals. Our clothes dryer, much older than the washer, merely buzzes when done, so I guess the musical washer is progress.