What's Up With Docs? - Embedded.com

What’s Up With Docs?

An article in the Washington Post 's business section revealed vendors' frustrations with users who will not read product manuals. The Post claims that customers prefer calling tech support over digging through the supplied tomes. Even car manufacturers now provide “quick start” guides that supplement the main manual, in an attempt to convey at least the essential info to the new owner. Vendors complain that users who don't read the manuals burn up too much expensive phone support time.

Balderdash.

Like most of us engineers, I buy a lot of high technology goodies. And, like most consumers, I hate reading the manuals. But much worse than a huge eye-glazing manual are the brief pamphlets that accompany today's products. Most are unreadable or devoid of content. The quick-starts are of dubious value and accuracy. Hey, you really don't have to tell me how to plug the thing in!

The last thing I want to do is call tech support and be put on interminable hold, listening to the whining falsettos of the Bee Gees interrupted at frequent intervals by a recording assuring me that this call is really important to the company. Those customers with the saintly patience to hang on long enough to get through to a support person then find themselves confronted with an individual who knows less about what's going on than most farm animals.

As a fairly knowledable techie, I find my intelligence insulted by support's patronizing assumption that all callers are idiots. A preemptive “I'm an engineer, I know how to insert the CD-ROM,” accelerates the call not even a nanometer per fortnight.

My HP Pavilion desktop is a nice machine, reliable and fast. The manual, such as it is, is so minimal it's nearly lost in the packing material. An on-line help facility offers little; web linkages predominate — not much help in one ultimately futile battle to get the DSL modem up. The 56kb standard modem, like most, eats up one serial port. Which one? No one knows. It's not in the manual, the on-line help is helpless, and tech support can do nothing other than repeat a mantra suggesting that it's COM3 or COM4, probably. Or maybe not.

Check out a video camera. My Sony has 57 buttons and controls, and it's a lousy camera. The docs are long on special effects and short on basic functionality. Some of the buttons will remain mysteries since previous experiences with Sony's support left me aghast and angry.

Early PCs came with a shelf-load of documents. The hardware book even included the BIOS source code and complete schematics. Not only were the books complete, they were elegantly cloth-bound, obviously valuable, and prized by owners. Yet in those days systems were very simple and there was little to know. Today's screaming computers offer myriad options, modes and features, with most unexplained and thus forever unused.

Products are over-featured and under-documented. Once software developer for a big consumer products company admitted to me recently that their products don't really work well, “because no one will actually use all those features.”

Cut the features, make it work, and give me a decent manual.

Jack G. Ganssle is a lecturer and consultant on embedded development issues. He conducts seminars on embedded systems and helps companies with their embedded challenges. He founded two companies specializing in embedded systems. Contact him at . His website is .

Reader Feedback

Amen, brother! (re: useless product manuals.) My pet peeve is the interminable list of “safety reminders” that come with any device which might contain perilous moving electrons. Do not remove protective seal while connected to power… Do not operate while sitting in bathtub… do not operate while standing ankle-deep in gasoline… do they seriously think we're going to read this nonsense? (Well, obviously I did once or twice.)

Manufacturers of complex devices like desktop computers shouldn't try to give us truly complete manuals — if they tried to approach the thoroughness of the DOS days, I suppose the manual set would be 50 volumes or more, and nobody would use it. But there has got to be a way to document what's truly needed up front, make the details accessible to those who can use them, and present it all in an organized, usable form.

As the for the larger issue of features vs. usability: I think the effects of profit motive, competitiveness and short-term thinking are obvious. But I also think it's a lot easier to find people who can grind out code, than it is to find people who can intelligently specify, design and document systems. Most projects I have worked on were “specified” by someone who apparently thought that if you threw a bunch of cool ideas into a Powerpoint presentation, like puppies into a basket, that constituted a specification.

Enough of this bellyaching. I enjoyed your column very much. Keep up the good work.

Caroline Rupp
Elegant Solutions


Part of the problem is the different level of user involved. Someone like yourself wants to know what goes on behind the blinking lights. Look at how PC's are marketed today – the primary target audience is the gaming and entertainment applications. This is typically a canned application with few options (stick the DVD in the tray) so manufacturers provide the simplest manuals possible – pictures only (a lot of people can't read directions anymore).

I also remember those cloth bound manuals – and it wasn't just IBM who made them that way. In the early PC days, just about every vendor offered a detailed technical manual on his product.

I also don't buy the argument that the manufacturers are offering – maybe if they would hire some english majors and have them learn how the product works, we could get some decent product manuals.

Yeah, right!

Tom Mazowiesky


Jack,

I always look forward to reading your columns– today's piece on the home page of embedded.com hit home. Like you, I've been using computers and computing equipment for a long time: about 23 years. I'm only 32, but I come from a family of engineers, so I got an early start. I hadn't thought about those old manuals for a long time until I read your piece today. And you're right, they were nicer and more complete.

But, you as well as anybody knows that those days and these days are different. What is my mother going to do with BIOS source code? Because really, my mother, your neighbor, and John Doe down the street are the valued customers of the PC makers. Those of us with EE and/or CS know-how usually end up going to the Web or the book store for the real dirt.

In my job, I am really on both sides of this argument. We're a small (about 30) company producing software and selling globally. We do our best to produce documentation that is correct and useful. But sometimes– like so many others– we screw up. There's nothing worse than explaining to your client that the document that you wrote yourself is incorrect. Because we have limited resources, we're forced to write the documentation ourselves as we can't really afford to hire special staff to do this. We get better as we go, hopefully not repeating the same mistakes.

As for the biggies like Dell, HP, Sun, and the likes, I have no excuse for them. If they can cut 1000 jobs when times are tough and still operate, then they should have time to write manuals.

Thanks for writing, keep it up.

Don Gochenour
Applications Engineer

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.