Your Giraffe Is Upside Down…


Reading a UK computer magazine last week, I came across the delightful phrase "like playing a recording of a swarm of hornets to a group of blindfolded mime artists". It conjures up a vivid mental picture of events such as might occur at a product development meeting where somebody suggests rewriting a whole legacy application in Objective Fortran and linking the components using DCOM. Or allowing the marketing department to choose the name for your wonderful new product.

Generally, I have to avoid such colorful language in the documentation I create. Somehow, flowery terms such as that may be felt to be taking the reader's attention away from the main points of the technical description, or even tending to make the software seem less than seriously "enterprise-capable". Let's face it, when you're trying to explain something like interception for virtual methods, or attribute-based validation at interface level, tempting users' minds to go wandering off and luxuriate in some wildly unrelated (or even humorous) description of the effects is unlikely to comply with the stringent rules of our style guide.

However, at the moment I'm writing guides that are not technically "documentation". They're designed to be entertaining and make it fun to learn about the products. I probably can't get away with a "Mr. Bunny's Guide" equivalent - which, for example, shows a Visual Basic Form in both front view (useful) and top view (just a straight line). Besides which, I'm no good at drawing pictures of farmers and animals. But, maybe I can sneak some vivid descriptions past the editors.

Perhaps I can describe the process of architecting an application as "like doing a crossword puzzle in a foreign language when they forgot to print the black squares and your pen's run out"? Or the complexity of writing a multi-threaded interception authorization behavior as "like explaining AC theory to someone who thinks the electricity leaks out of a light socket if you don't put a bulb in it"? And how about painting a picture of reaching feature complete and code freeze for your product as "like trying to finish a bowl of soup when sitting outside a French café in the pouring rain"?

Unfortunately, one of my U.S. colleagues once described me as having a "British sense of humor" (notice that he missed the "u" out). I guess this is where it will all fall over because it's likely that a large proportion of the readers will have no idea at all what I'm talking about. Especially when it's been translated into a range of other languages. And I suppose it could get quite annoying if you have to re-read the same section a few times just to grasp what’s going on. Oh well, it was a thought.

Mind you, talking of animals, several years ago a co-author and I decided to have a competition to see who could get the most lifelike picture of an animal created as one of those "boxes and arrows" schematics into a book. I managed to get an only-marginally-recognizable dog into one of mine, including the Internet "cloud" symbol for the result of processing various inputs - neatly positioned just below the tail. I assumed they'd cut or modify it during edit, but to my amazement it actually survived intact. I never did get round to mentioning it to the publisher. However, my co-author won the competition hands-down by including a very realistic giraffe, and disguising it by drawing it upside down. I complained about this, but he simply reminded me that the rules didn't specify orientation.

And I guess that, if my editors read this, it's a lost cause now anyway. They (and our customers) will be seeing animals in all of my schematics. Maybe I've just invented a new form of the Rorschach Ink Blot test.

Comments (2)

  1. steven says:

    Nice similes, but now you’ve gotten me really curious as to where the giraffe and dog are. How about some image links or at least the book title?

  2. Alex Homer says:

    Thanks Steven. I seem to remember the book was the original Wrox version of ASP.NET Distributed Data Applications (http://www.amazon.com/ASP-NET-Distributed-Data-Applications-Homer/dp/1861004923), which it seems is available at the bargain price now of just one cent! I guess I won’t earn much royalities from that…

Skip to main content