Do your users know WTF you're talking about?

"This is just the kind of synergistic, customer-centric, upsell-driven, out-of-the-box, customizable, strategically tactical, best-of-breed thought leadership that will help our clients track to true north. Let's fly this up the flagpole and see where the pushback is."

That's from a book I'm having fun reading, Why Business People Speak Like Idiots, but in that kind of "Oh that's scary how true that is..." way.

The book is about bullshit business speak (like the kind you play buzzword bingo with in a meeting), but it applies just as much to the way a lot of technical documents and books are written--with so much jargon it's painful. The book talks about four traps that people fall into that leads to this kind of crap, but I'll leave that to you to read on their web site.

I'm trying to get off my how-to-make-a-bestseller rant (unsuccessfully), but taking the advice in this book is useful for anyone writing anything. When we've seen authors we work with fall into a trap, it's almost always out of fear or the inability to imagine another way (the just-do-what-everyone-else-does syndrome). The fear is about imagining what reviewers and readers will do if the author doesn't cover every possible base and be as technically complete as humanly possible. They imagine that if they try to simplify things, someone will think they aren't expert enough.

You're worrying about the wrong people! The people most likely to criticize you for lack of completeness aren't your target audience anyway. The only people who matter are your intended readers. So it gets back to the other points I've been making in the bestseller posts -- are you writing for how you'll be perceived or are you writing to enhance the reader's life? The answer changes the content.
Get you out of the way, and chances are your readability will go WAY up. (Unless you're already a good writer. But for the rest of us, like me, this doesn't come naturally.)

Think of how many times you've read a techical document like a book or white paper or maybe even your camera manual... and found yourself looking at a paragraph, and having no f'n idea what it actually says. You flip back a few pages to see if maybe you skipped something crucial that might give you some context for this impenetrable passage. But no, it's just a cliff as we call them. (The last pass we make through all Head First books is the "cliff test", where we attempt to find, and patch if we can, any cliffs that still made it through the review process.)

So what do you do as a reader when you come across one of these wtf sections? You re-read it. Again. Again. You stare at it harder thinking that if you just... keep... staring... it'll suddenly make sense. That's like speaking louder to someone who doesn't understand the language. They don't have a hearing problem, and you don't have a reading problem. The message is just not in your native language. Or anyone's, apparently. Last night I went to Amazon (I know, it's a love-hate relationship) and paid $29.71 for a user-friendly manual for my Nikon 5700. It looks photocopied, bound at Kinko's, but I didn't care, because it has to be better than the actual manual that shipped with the camera. And I have no idea why they can't make most consumer electronics manuals more reader-friendly. Ditto with virtually any piece of professional audio equipment. (Like anything by Roland, and Yamaha isn't much better).

Anyway, the "fight the bull" book makes some of the same points many of the marketing bloggers have been making--namely that people don't trust bullshit speak. Users, customers, shareholders, employees... they recognize it, and they hate it. But if you do need to hold your own in a meeting, and especially if you're going to create a mission statement, our Head First Java book (both editions ; ), includes a Phrase-O-Matic generator example as one of the first introductory code examples in the book.

So here's the ultra-simple beginner's version for our Java newcomers:
(If you want to do it the old-fashioned way, just pick one element from each of the three lists, in order.)
================
public class Phraseomatic {
public static void main (String[] args) {

// make three sets of words to choose from
String[] wordListOne = {"24/7","multi-Tier","30,000 foot","B-to-B","win-win","front-end", "web-based","pervasive", "smart", "six-sigma","critical-path", "mission-critical", "dynamic", "synergistic", "proprietary", "heterogeneous", "scalable", "change-capable"};

String[] wordListTwo = {"empowered", "sticky", "valued-added", "oriented", "centric", "distributed", "clustered", "branded","outside-the-box", "positioned", "networked", "harnessed", "focused", "leveraged", "aligned", "targeted", "shared", "cooperative", "accelerated", "best-of-breed","fault-tolerant"};

String[] wordListThree = {"process", "tipping point", "solution", "architecture", "core competency", "strategy", "mindshare", "portal", "space", "vision", "paradigm", "mission","thought leadership", "infrastructure", "life-cycle"};

// generate three random numbers, to pull random words from each list
// the random number is based on the number of words in that list
int rand1 = (int) (Math.random() * wordListOne.length);
int rand2 = (int) (Math.random() * wordListTwo.length);
int rand3 = (int) (Math.random() * wordListThree.length);

// now build a phrase
String phrase = wordListOne[rand1] + " " + wordListTwo[rand2] + " " + wordListThree[rand3];

// now print it
System.out.println("What we need is a " + phrase);
}
}
================

I'm counting on y'all to do your part in stamping out the corporate bullshit in every place you find it, but most especially in materials that users are trying to learn from. And remember, the word is "users", not "utilizers" : )