We open this little story with David and Ducas having an IM conversation over Ducas' choice of "why is documentation so boring?" as an IM tag line:

David Burela said: you just need to punch it up a little

David Burela said: add a little drama

Ducas said: so, explain a crud wcf service with drama...?

David Burela said:

"They had a contract which destined them to meet. Although they met and shared something important, the encounter was only a temporary connection. Although they are now disconnected from each other, the memory shall persist on"

Which tickled the fancy of David and prompted him to pose the question to the internal Readify Tech list:

Anyone else got some good soap drama between components?
A Romeo and Juliet story between C# & VB?

To which I initially replied:

C# eloping into the night with VB.Net?

I'm having trouble picturing that... although I must admit to finding the thought of a known fan of C# such as... say... Mitch... reciting the something like the following brings a small smile to my face:

But, soft! what light through yonder window breaks?
It is the east, and VB is the sun.
Arise, fair sun, and kill the envious C#,
Who is already sick and pale with case sensitivity,
That thou her maid art far more productive than she:
Be not her maid, since she is envious;
Her rampant punctuation is but sick and green
And none but fools do wear it; cast it off.
It is my lady, O, it is my love!

Me, being the big meanie that I am, couldn't go past the opportunity to have some gentle jest with the words of one of my favourite authors mixed with a product that has consistently broken my geeky heart:

It is important to note that suddenly, and against all probability, a SmartPhone had been called into existence, several miles above the surface of an alien planet. But since this is not a naturally tenable position for a SmartPhone, this innocent creature had very little time to come to terms with its identity.

This is what it thought as it fell:

'Ahhh! Whoa! What's happening? Who am I? Why am I here? What's my purpose in life? What do I mean by 'who am I'? Okay, okay, calm down, calm down, get a grip now. Ooh, this is an interesting sensation. What is it? It's a sort of a tingling in my... well, I suppose I better start finding names for things. Let's call it a... pen! Yeah! Pen! And hey, what's this roaring sound, whooshing past what I'm suddenly gonna call my screen? Wind! Is that a good name? It'll do. Yeah, this is really exciting! I'm dizzy with anticipation! Or is it the wind? There's an awful lot of that now, isn't it? And what's this thing coming toward me very fast? So big and flat and round, it needs a big wide sounding name like 'Ow', 'Ownge', 'Round', 'Ground'! That's it! Ground! Ha! I wonder if it'll be friends with me? Hello Ground!'

But after thinking about for a while over lunch, I came up with following, slightly more serious, response:

Documentation for fun and profit

I'm a huge fan of making documentation interesting (and hopefully fun) and have no idea what the point of producing dull documentation is.

If the point of documentation is to communicate an idea then seems to make very little sense to sabotage that concept with a delivery mechanism that is actively discouraging that very act.

Imagine your intended audience. If they're going to be struggling to stay awake during the discourse of your little phonebook style tome and resentful afterwards for having to loose a portion of their lives wading through it, what do you think the chances them actually retaining any of the supposedly important information is?

There are two objections to producing "interesting" documentation that regularly get put forward and I'm yet to be convinced by either one of the them:

The Corporate Image

The classic 1950's "You're here to work, not have fun! Pull your socks up! Straighten your tie!" attitude continues to haunt a lot of us to this day. We feel guilty about anything that drifts away from the stern approval of the stereotypical "bank manager" type from our (grand) parents day. If it's fun it mustn't be work related.

To that I say "Pfft!".

Documentation is just like anything else your company produces. It has the chance to entice, enrapture and engage your customers and staff... or it can put them to sleep.

It's the 21st century and guess what? Nobody is interested in being bored to death by reams of tedium.

You wouldn't dream of spending hundreds of man-hours and squillions of dollars each year producing bad advertising and marketing would you? Well that's what a lot people do with documentation.

They spend who knows how many hours and dollars describing their wonderful new creations... in a format that so tedious and boring they may as well have just locked the product and the documentation in the basement for all the good it's going to do.

Bob from Accounting

(Apologies for falling back on yet another bad stereotype here but I get the feeling that using geeks as a negative example would be detrimental to my cause :)  )

The second objection to producing interesting documentation is that not everyone can do it. Whether it's a beautiful menagerie of Visio diagrams or a 'page turner' of a description, not everyone has it in them to produce interesting material.

My argument to this is: don't make them.

Just like you wouldn't attempt to force a dentist to fix a jet airliner engine, don't force people who can't write to write.

There's little point.

At best, you and your customers survive the trip. At worst, its a grizzly mess of morale nose dived into the ground and a whirlwind of large paper doorstops scattering across the neighbourhood.

If you don't have someone in your organisation who relishes the chance to produce exciting printed material then hire someone who does. Just like those weird brightly coloured personalities that you hired to market your wares, good technical writers are a very good way to ensure your message actually gets through to your intended audience.

So....

What are you waiting for?

Go forth and write that epic take of love, loss and the inner working of the JRX-382!

You've got nothing to lose and everything to gain. :)

PS: Yes, I too recognise the irony of someone who struggles with the whole communication thing, attempting to tell others how to communicate. Don't blame me. Blame people like Infocom who had the temerity to demonstrate how to get away with such wild and whacky behaviour back in 1989: http://www.mv.com/ipusers/xlisper/zil.pdf