An Open Letter to Technical Authors

This is addressed to you, you übergeeks who spew out endless books intended to help us learn the wiles of .Net, the secrets of COM+ and so on.

I have two gripes with you lot, so listen up.

Problem 1: Boring Business Examples

Why are your business examples so boring? Why are they so devoid of creativity?

Here are some rules and I want you to follow them:

  • Don't use examples from the publishing world.
  • Don't use HR departments as examples. They have been used one million times too many.
  • Don't use "northwind".
  • Never ever under any circumstances use the word widget.

The next time I see Widget used in print, the author and publisher will both be named and shamed.

When explaining polymorphism:

  • don't use examples from the animal kingdom.

Why not try inventing new metaphors? Why not dip into the right side of your brain and see if somewhere in there you have a smidgen of creativity?

Perhaps the new examples might be more illuminative than these sad cliches. Perhaps they could help broaden our thinking - make us understand the concepts in a less cliched way. And hopefully the examples you create can be vivid enough to stop us from falling asleep in our cubicles.

Problem 2: Poorly Formatted Code Examples

Check that the example code actually compiles. Is that really so hard? If you change something - no matter how small - then recheck the code using a compiler (at the very least).

If you are rewriting C# into VB.net, please take care! Check that the resultant code will compile. Check that it is a **good** example of VB.net.

But there is a worse crime of which you are all so very very guilty.

Is it 1968? Tell me? Is it 1968?? It's not 1968! Code editors use colour to highlight syntax. So why don't your code examples?

On web pages, colour is *always* available. Yet you fools (and I'm looking at you MSDN) insist on serving up code in one colour only. You hurt my sensibilities.

I understand that colour is expensive to provide in print. But it's free on the web. And in books you can use bold to highlight keywords you ninnies. And don't tell me you can't afford the ink!

Use a non-proportional font. (Break this rule and I'll send my boys around to break your legs)

Embed the code in a light-grey box so that it is separate from the supporting text.

Do everything you can to make your code examples easy on the eye.


Follow those rules and nobody gets hurt. Capisco?

 

I'm currently writing a book about how to build your first product. If you want to build your first product, please sign up to be notified when the book is available.

(By the way, I read every comment and often respond.)

Your comment, please?

Your Name
Your Url (optional)
Note: I may edit, reuse or delete your comment. Don't be mean.