You are here

Sounding Off: Writing Manuals

David Greeves By David Greeves
Published July 2004

Who'd want to be a writer of manuals? The endless showbiz parties, awards, book-signings and... hang on a minute...

Spare a thought for the instruction-manual writers of this world. Like the poor souls who stick stickers on bunches of bananas (saying 'Chiquita' or whatever else) or go round amending the timetable at every bus stop on the route of the number 23, we pass by their life's work without ever wondering who they are. And their work is surely more notable, with all due respect, than that of the timetable putter-uppers or banana-sticker stickers — writing a 1200-page manual is not to be sniffed at, even if it is the work of more than one person. After all, reading a 1200-page manual is no mean feat, and it's one that is rarely attempted.

Writing Manuals: David GreevesI wonder if this offends them? I wonder if, one day, our manual writer, moonlighting in the customer support department, takes a call from a confused customer who's having trouble with the software's quantising features, and realises this can only mean that his lovingly written explanation of this subject ('Appendix F: MIDI Timing — Quantising, Grooves and beyond!') has gone unread. Does he shed a silent tear, and die a little more inside?

Perhaps the general neglect of the manual-writer's craft contributes to the slight lack of enthusiasm that one detects in many manuals. In any case, there's little room in writing one for self-expression. And that's the way it should be — creativity and enthusiasm have no place in the instruction manual! I'd rather have a manual that's thorough, straight to the point and dry as dust than one which tries to be clever or funny. I may be on my own here, but a manual which includes light-hearted interjections and humorous captions is the paper-and-glue equivalent of that odd man down the pub who thinks he's your friend and is always laughing at his own jokes. Why not go the whole hog and add an animated jack plug which pops up in the corner of the screen and says things like, "Hi there! I see you're creating a virtual instrument track. Can I help you with that?"

That aside, when you consider what manual writers have to put up with, I think you'll agree that they do an excellent job — most of the manuals you see these days are decent enough. Some are very bad and nearly all are fairly ugly, but most are very good. Nevertheless, they all seem to follow the same conventions.

Take, for example, the obligatory 'troubleshooting' table at the back. I'm sure they can be useful sometimes and, from the manufacturer's point of view, they probably pre-empt a few calls to customer service (perhaps preventing a few more knocks to our poor manual writer's fragile self-esteem), but I can't help feeling that their format limits their usefulness somewhat. Most problems that can be solved in 15 words or less shouldn't really need explaining, and most things that you really need to be told couldn't possibly be explained in 15 words. And there are always a couple of entries which don't tell you anything at all. You know the sort of thing I mean. 'Problem: Unit has no power. Cause: Power is not connected. Solution: Connect power'. There's something satisfying about a concise explanation of the head-slappingly obvious — I'm sure philosophers have a special name for it. Perhaps some form of mystic religion could be built around the reciting of these mantras — repeat after me: 'The cables are faulty. Replace the cables'.

Some manuals seek to further bemuse the reader with a web of indices, appendices and cross-referenced footnotes that threaten to trap you in an endless loop. But others are striking by the sheer lack of information contained within, or by the indecipherable way they present it. I recall a particular Russian-made mic (admittedly not a difficult thing to operate) which was accompanied by a small, unevenly cut booklet containing what appeared to be hand-traced frequency graphs and a few hand-written notes... in Russian. Perhaps they took the word 'manual' to mean 'done by hand'. It's just a shame they didn't have a stab at translating it into English — the results would have been priceless.

I'll leave you with an excerpt from a manual, the rest of which has long since been lost, which hangs on a notice board in a corner of the Sound On Sound office, a benchmark in the field of incomprehensible technical writing which has seen off many a challenger over the years. If anyone can produce a better example, I'd like to see it, and if anyone can work out what the following actually means, I'll be really impressed!

"Part 1: Be able to adjust the revolution of knob. Using adjustment metal not spring or cushion as usual, the revolution smooth. Use the fitting adjustment tool.

"Part 2: It is housed part of the gear into case. As grease is not leak, part of the shaft and gear is greased safficiently [sic]. Therefore it is low in rotary resistance and surpass others in endurance.

"Part 3: Winding shaft and gear is unification processing. It is new manufacture whose screw is not loose and whose knob is fixed with the shaft."

It's a dirty job, but someone's got to do it!

About The Author

David Greeves is Sound On Sound's News Editor. He believes that everybody has one good manual in them. Someday, he'll write his.