Slashdot Mirror
RTFM = Read the Funny Manual?
coronaride writes: "This article over on Wired discusses the issue near and dear to every sysadmin and support tech's heart. I, myself, never read any manuals that accompany the products I buy (but when does cheese-whiz really need instructions anyways?) unless something majorly goes wrong! The article talks about how some countries, including Japan, try to spice up their product manuals in order to entice the users to read them. Is this just too much work for our lazy American manufacturers to do?"
Randal Schwartz's first O'Reilly Programming in Perl was also fun, for the humor placed in it, which keeps the student amused rather than dry, clinical and boring, which IMHO the 2nd edition was.
Some people view humor as a distraction in documents, perhaps so, if the humor gets in the way of getting the information across. I try to put some humor into sample data and documents, but usually it takes someone with special knowledge to notice (i.e. an address for J. T. Kirk, 1701 Enterprise Place) or silly things to fill in space in an example form, like creating combinations of funny words randomly to fill out the space in a new P.O. form. (BTW, programming in PCL sucks!)
It also seems to make the job of writing documentation a bit easier.
A feeling of having made the same mistake before: Deja Foobar
I remember one copy of another of Corel Paint that included a little mini-book like thing that was basically a complete description of the entire printing industry that went all the way from base color theory (all of them, yah!) to how to take care of half-tone printing press problems.
::shivers:: one of the few programs that is darn nearly physically painful to use. . . .
I still use the thing as an occasional reference, very nice pack-in.
Now that particular version of Corel Paint on the other hand. . . . sucked. Big time. Apparently it has gotten better since then (heh) but I am not going to spend more $$$ finding out. . . . ickies. Awful nasty program
Need help treating your acne? Come here!
"We have noticed that if a manual said, 'Do not ever do this,' we would then get many calls from people who had broken their machines by doing just that," Esposito said. "They read the documentation and took offense to its tone so they had an argument with the product."
I found this to be an amusing story. However, the best way to deal with the whole manual issue is to design your product better. You know how you're not supposed to remove a game cartridge while you're playing? If you look at the SNES and the GameBoy, you are physically prevented from removing the cartridge because the power switch moves a piece that blocks the exit of the cartridge.
I realize this won't work in every situation, but the solution of 'we need to get people to read the manuals!' isn't going to go very far.
Getting back to the SNES example, I read the manual before playing the machine. Heck, I'm an expert on it! I used to sell them! Despite my detailed knowledge of how the machine works and the consequences of pulling the cartridge out while it's on, I'm still aware of the power switch blocking exit of the cartridge. Why? One day, a friend of mine came over with a new game I had been waiting for for ages. In a rush to pop this game in, I gave the cartridge in the machine a pretty good tug. Fortunately, it didn't give though. The safety feature of the SNES prevented me from making a 'wandering mind' mistake.
In cases like that, you could know the product inside out and still make bone-headed mistakes like that. Fortunately for me, Nintendo was smart enough to anticipate that I might make a mistake like that and design it so it's not easy to do.
"Derp de derp."
Mackie (sound reinforcement and processing) is another company who puts some humor in their manuals - the manual for their 1604VLZ mixer, for example is full of material that, while not being laugh-out-loud funny, is also not man-this-is-so-boring-I-want-to-die. The effect of this is that I have actually read the whole thing, cover to cover, and learned a whole lot more about the product than I would have if they had just gone with the standard technical writing standard.
If all the world's a stage, anyone who says they want better lighting spends far too much time in a dark theatre.
But once they start putting examples (this is where my dander usually gets up, for the lack of) a little inside humor isn't necessarily a bad thing. Yes, putting cartoons, particularly those in some of the older computer books I've read, fall flat, because the humor is lame or dated, and waste space. But there's nothing wrong with using 'foo' 'bar' or 'fnord' in examples. Unless the reader is so dense they take it literally, then you have to question why they have the book in their hands and rip it out of them before they do something really dangerous.
A feeling of having made the same mistake before: Deja Foobar
When I worked for Fifth Generation Systems (Fastback, Direct Access & Suitcase), the person in charge of producing manuals used to do this on purpose to "F" with management because they never read the manuals or even knew what the products really did. I guess this is why the company was sold to Symantec for a bargain basement price.
Strange women lying in ponds distributing swords is no basis for a system of government.
I have a Prime manual from the early 1980s that has a long running joke in it.
It is a manual for a version of "runoff", which is used for formatting documents. The examples given in the book are for a restraunt chain that servers "frog burgers". There are a whole bunch of Cthulhu references throughout.
I need to scan some of them and post them to the net. Pretty funny.
Another example is in the error return values in GLIBC. Included are EIEIO and EGREGIOUS and other bogus errors.
Unfortunatly all traces of humor are removed from manuals, not due to burn out or other causes, but because Corporate America sees them as "Not Profesional".
Funny documentation and Easter Eggs are both a causualty of the War on Fun.
"Trademarks are the heraldry of the new feudalism."
I don't know about software manuals, but when I was a 9 yr old kid I got my first bruised knuckle replacing a starter in a volkswagon van (also happened to be my home :). I found the manual to be very helpfull and quite entertaining, I believe it was called "How to keep your volswagen alive, a repair manual for the complete idiot". Very well written and full of highly entertaining bits. I wish more manuals were written in this style.
:)
Ahhh, nostalgia, but I would not own a VW even if it was given to me, easy to work on but you had to, all the time
-- The morphemes of your disquisition are ascertainable, but they have eschewed an ambit of transpicuous exposition.
I skimmed the manual for a piece of internal software my company had created and found a note that basicly read, if you've gotten to this point fax in this form and we will send you a copy of Myst.
I read a while ago (no, I can't find a reference) that a bank sent out an update to the terms of service for their credit cards. Buried somewhere in the middle was a line telling you that all you had to do was call a number and they would credit your account $5. They wanted to see how many people actually read the change.
IIRC the response rate was under 1%. I try to tell myself[1] that they weren't doing this as a prelude to screwing their customers even harder.
[1] What I say when I don't want to think about something I have no control over that I am absolutely convinced is true.
Nope, no sig
How to Keep Your Volkswagen Alive for the Compleat Idiot by John Muir (can be found or ordered at a local bookstore)
It's a repair manual so well written that I read it more than once, even before I had a VW. It taught me a lot about auto repair, and reinforced what I learned in High School auto shop.
He's funny. He has nice line drawings.
He also editorialized. He refused to explain how to fix an automatic choke because he felt that the choke was bad for the car. The choke allows you to drive the car before it's warm. His suggestion was to roll a cigarette while waiting for the car to warm up, rather than cause excessive wear by putting a load on a cold engine. The edition I read was definitely an artifact of the 1970s.
Unfortunately, most manuals cannot be written in such a literate fashion. He had the luxury of explaining auto maintenance. These are concrete, well-understood, and intuitive concepts. The example vehicle is the air-cooled VW, technology is well over fifty years old, and consequently simple.
I usually need manuals (for instance) to document a poorly designed or arbitrary interface to a product whose mechanism of action I may not ever fully understand, and will (if I am lucky) never use again. Sometimes I need manuals to provide detailed specifications for an implementation of a process that I already understand well. Neither of these is much of an opportunity for an author.
There are still plenty of opportunities for well written manuals, but since most vendors seem to regard mere accuracy as a luxury, I never expect them to be literature.
Assembly is the reverse of disassembly.
I'll never forget -- when I was just a kid, back in the mid-late eighties, my father had just upgraded our Macintosh to a Mac Plus. As he was reading one of the owner's manuals, he started laughing, and I asked him what was so funny.
"Oh, nothing," he said.
Still, I pressed him.
"It says here in the setup steps, 'First, eat some chocolate'".
"What's that supposed to mean?" I asked. I honestly had no idea why "Eat some chocolate" would be written in a computer manual.
"Oh, programmers are just weird," he chuckled.
Ever since then I've had a healthy respect for computer programmers.
"First you gotta do the truffle shuffle."
instead of "this page intentionally left blank", they should use a graphic design, such as the company logo (!) in page corner. No one's intelligence is insulted and the design does not need to localized to different languages.
cpeterso
in last weeks paper. It's online. Geared more toward consumer electronics but more interesting then wired's column.
Bad boys rape our young girls but Violet gives willingly.
The article talks about how there are companies whose sole function is to take native documentation and translate it into another language. Sounds easy, but it's not. These companies deal with all sorts of native land societal, religious and fundamental PC.
Different societies have different views of their world. For example, in the U.S., documentation tends to use a lot of humor to keep things light and lively. This isn't so in Europe. Hungarians know that everything will eventually break and being the industrious do-it-their-selfers they want their manuals to read like a Chilton book. Japanese manuals often contain creative cartoons that if placed in another country's documentation, viewers may not take the company and their product serious.
Another humorous tidbit included several paragraphs describing an event where the box-art for Painter 5 contained a left opened hand palm with flames coming out of it. The article indicated that in several countries the left hand is considered unclean and showing the open palm is extremely offensive. The cake icing flesh burning wasn't smart too.
Though I found the article somewhat lacking is detail. Countries even take offense to certain fonts and colors being used. This is one of the main reasons why most companies like Macromedia, Microsoft and IBM tend to go take the safe route and from the get-to use ubiquitous type styles and colors for their corporate branding, product designs and websites.
All in all this article was is a great read.
grep >= ! == $your
Jokes and Gags make for good memorable content for your brain to draw upon when you are trying to remember how to do something or how something works.
.) painful.
Many Cram Courses rely on dirty limericks to allow students to memorize patterns quickly, and the best books on anything that I have read have at least some humor in them.
Hell that is why on any given day I could read through a few thousand pages of Asimov talking about almost ANYTHING but damned if I could do the same reading for a textbook even in a topic I am interested in.
My logic textbook has SOME humor in the logical examples, but the actual writing is so bone dry as to make reading it straight through (or even for one chapter. . .
There are two chapters where the author lets up, and they are an absolute blast to read, easy to remember material from, lots of readily applicable examples pop into the readers mind when needed. Too bad the entire book is not written that way.
Need help treating your acne? Come here!
On a US Federal Governement document, I saw a page with no text except, in large letters in the center:
THIS PAGE IS BLANK
Kind of reminded me of all the area 51 Gags. You could always get a laugh going up to a guard in full military attire, and getting him to deny that he works for the US government. And, of course, they're always guarding 'nothing'.
Slashdot gets worse every day... Pipedot: News for nerds, without the corporate slant
Dr. Dale Dubin put a message into his book (the 50th printing of "Rapid Interpretation of EKGs") that offered up his Thunderbird if the publisher was contacted. Of the 60,000 students who bought the book, only 5 contacted the publisher.
h tm
http://www.snopes2.com/college/homework/foundcar.