A friend sent me an article about the ongoing demise of hardware and software documentation in the tech world. I have found this trend vexing because a) I have been paid to write tech manuals and b) I actually READ the frickin’ manual (RTFM) when I have a question. Since this entry’s lengthy and I know you folks are busy, the short version is: tech manual readers must depend on third-party online help, which is often written primarily by programmers for programmers and assumes a certain level of knowledge that not all users share. There is still a place (and market) for detailed explanations of technology features or functions. If you have a few more minutes, you can read more of my reactions to the death of documentation.

Horror stories for dinosaurs in the paperless world

I’m sharing some more war stories to better dramatize the ill effects of insufficient documentation. Take them as you will, the problems are real.

Software version changes

Nothing can make a long-time Microsoft user crazier than a major version change. I remember the shift from 2003 to 2010 when I was at NASA. We were taken to a class and given an overview of some (this word is key) of the major new features/changes. Then we were sent back to our desks, told to install the new versions of Word, PowerPoint, etc., and sent back to work.

The transition was a mess. Just trying to get the software to start going was a headache: you had to click on the subtly flashing button at the lower-left of the screen to start everything rolling. The “ribbon” of commands on the menus had changed locations, individual commands that long-time users counted on to make their lives easier relocated and had to be hunted down, and even some keystrokes that had been second-nature had just plain disappeared (I’m looking at whichever genius eliminated the use of F2 to edit cells). So productivity suffered for a week or two because the users were not given a full briefing with much more than a couple pages of documentation (or the always-dubious “real language” F1 Help) to get things moving.

Acquiring a smart phone for the first time

When I bought my first iPhone in 2009, I popped open the box and dug around. I shrugged and asked the blue-shirted clerk at the Apple Store, “Where’s the tech manual?”

She smiled brightly and said, “There isn’t one!” I was aghast. Though I had tried my best to cover my long, scaly tail and spine plates, I found myself asking, “How the heck do you know how to use it?”

The Apple Store employee assured me that the interface was so simple that a technical manual was unnecessary! She took a little time to point out some of the basic functions by pointing to them and demonstrating how they worked via literal hands-on interactivity. Other, specialized apps could be downloaded from the App Store icon. Suitably chastened, I took my new, manual-free gadget back to the Bartcave and tried to make sense of it.

The tool was intuitive to a certain extent: it relied on the unstated assumption that the user has had some experience with icons and windows-based screens, which I had. However, some of the little features–like being able to expand or shrink a screen by placing two fingers on the screen and pulling them apart–I learned from another user. My question to him was, “How was I supposed to know that that feature existed?” Shrugs. “Where did you learn it?” From other users, as it turned out. And how did those other users learn about the feature? Blank looks.

I griped up a storm when I had to make the transition from being a 20-year PC user to Mac. You can read that elsewhere.

How online helps works today

What the linked article explains is that many people learn about their electronic gadgets online, via videos, discussion groups, and other online tutorials–many of which are not developed by the original equipment manufacturer. I’ve been pressing F1 for Help for 20+ years. Others, however, won’t even do that.

Tech support, Silent Generation style

My father, who first encountered computers sometime in the computer Triassic Period (think punched cards), refuses to deal with online help or F1. Actual discussion…Me: “Why don’t you press F1 and use the Help function? You know some tech writer got paid good money to write that.” Father Dan: “Because I’ve got you.” This is the same man who has a well-used paperback doorstop of a book for using Windows Excel…98.

Which brings us to the current era, where the mammals (third-party video-based instructors) and the arthropods (search engines and smart online help) are duking it out for domination of the online help world. Who will win out is anyone’s guess. People seeking paper manuals or step-by-step processes might as well be asking for velociraptor meat. And the pace of evolution is accelerating.

The “fun” of learning the hard way

I talked about this no-documentation phenomenon with a video game designer recently. I asked him if he included any sort of manual for his games. He said no, the players don’t really use them. The games often come with a “training module,” where you can experiment with the various controls without consequences (i.e., irritating team members because you’re a newbie). Also, there are little back doors and tricks/cheats that users can pick up to acquire new abilities or advance levels or whatever. These existed when I was a kid, too, and I expressed some curiosity about where did these people get their information in the first place?

But essentially, video game players pick up their controller and wing it. Try selling a business on a word processing or spreadsheet software with that philosophy and see how far you get (I’m guessing we’ll find out soon enough). I will say this for Microsoft products: while the paper manuals and books are disappearing, the F1/Help feature has become more thorough.

The only challenge I encounter with comprehensive help systems is that the programmers don’t always use the same words to describe a function that a user might, especially if they try to write your query in form of a question. Still, it’s an improvement over that little animated paper clip assistant.

Reverse-engineering software to create documentation

One of my many duties at Science Cheerleader is being more or less a “super user” for the internal database. Fortunately, I had worked with and created documentation for a similar database system when I worked at Disney years ago; otherwise, I would have been hopelessly lost. How did I learn to use a database at Disney the first time? That’s right: an all-day class and lots of book reading.

I was thrilled when SciCheer got an actual database to replace an Excel-based spreadsheet I’d been keeping for our records. The DB was not, however, particularly intuitive, so I had to become the translator between the interface and the user. Just around the time I had things figured out, the DB underwent a complete user interface redesign. Naturally everything was moved around and controls had to be relearned. Again, no documentation. As with my attempt to use an iPhone fresh out of the box, the people designing the interface assumed some past knowledge of databases. If you know how databases work, the rest is, theoretically, “intuitive.” If not, you need to take a class or read a book on how they work. Or, I suppose, you could always try Google.

Interesting/related side note to this: when I did create front-to-back documentation for the DB, I found that nobody was using it. The default “help” was to email Bart. This weekend, I took a stab at reducing the number of words, increasing the number of pictures, and focusing only on the need-to-know functions. We’ll see if that gets more play.

Migrating a website

One of the truly vexing things about online “help” pages–and now I’m talking about pages put out by Google, WordPress (sorry, guys), or Apple–is that they, like the people who designed my iPhone, assume a certain level of knowledge and competence in the digital realm.

Just doing something “simple” like purchasing my domain name, moving it to another web service, and creating a domain-specific email address required numerous discussions with a friend who designs websites for a living. In short, she was already a coder and spoke the lingo. She would find a page, point me to it, and say, “Copy and paste all that text from this page onto the appropriate fields in WordPress.” Seriously, I tried that. The documentation, however, was incomplete as far as a detail-minded tech writer like me was concerned. There were pages for each of the domain types and redirect code you were supposed to paste somewhere for each domain type. However, instead of there being just one field to copy and paste to, there were half a dozen and no instruction for what to put into those fields or what they even meant.

Final thoughts

The major drawback of online “help,” then, is that often it is written by coders for coders who already speak the language. It assumes too much and is incomplete if a “dummy” wants to take care of something him/herself. Maybe it’s becoming rarer for people to take the time to read text and follow the directions so they can know what’s going on. This willful ignorance exacerbates the digital literacy portion of the digital divide. As our computers become more complex and their inner workings more mysterious, this can’t be good, can it?

My humble opinions:

• Computer literacy needs to be a standard part of school curriculum.
• Even if users become more computer literate, documentation would do better to err on the side of over-explanation. This is the sort of thing technical writers can do to make the world a better place: serving as ongoing translators between Engineerish and English (or any other language spoken by humans). Someone needs to speak for the users and ensure that their needs are met.
• If an enterprising computer-savvy publisher/technical writer wants to make a little money, they could do so by filling that gap between the manual-free “intuitive” functions and the super-user problems, which users are not going to need to solve very often but when they do, should not need to hire a programmer to execute.

In other words, there is still a need, demand, and paying market for detailed printed technical manuals that take the time to explain how software works in the real world.