"How Tech Writing Sucks: The Five Sins," from interface designer Amy Hoy, addresses five ways in which we, as a community, fail to communicate. Addressing the ability to write is important, since the internet is ultimately about communication between people. If you can't communicate effectively, nobody will care about your message, no matter how worthwhile it is. One wishes that Sun would get that in their heads once in a while. The five sins, Ms. Hoy says, are:

• Losing the reader
• Making the reader feel stupid
• Failing to stick
• Being a total bore
• Not providing much-needed context.

Most of these are obvious, but they all fail from a misunderstanding of what technical writing is supposed to do: inform and instruct (in varying qualities.) She even offers a three-step attack plan to fix it:

• Describe the symptoms
• Identify the underlying causes (admitting you have a problem...)
• Attack! (a prescription for betterment)

Now, your Humble Editor can only hope he doesn't hit too many of those sins... (have I lost you yet?)

More concisely: [...] The author had violated the number one rule of good writing, the “Show, don’t tell� rule. There was not a single story in the book. It was chock full of sentences like “A good team leader provides inspiration by setting a positive example.� What the eff? From "Introduction to Best Software Writing I" By Joel Spolsky http://www.joelonsoftware.com/articles/BestSoftwareWriting.html

From "Introduction to Best Software Writing I"
By Joel Spolsky

http://www.joelonsoftware.com/articles/BestSoftwareWriting.html

That's a pretty goood rant :-) I agree that stories can spice up a book, but beware of overdoing it. "The wisdom of teams" by Katzenbach & Smith is a prime example. In general it's a good book, but it seems a bit too much like a collection of anecdotes. For books which are not technical references, I prefer that the establish a sound structure which helps synthesize the message and then spice it up with stories. Another nice point from the article is the 2000+ pages written by 16 authors. Multiple authors writing a book requires great preparation, dicipline and postprocessing. There are two many examples of this kind of book, where it seems more like the authors just submitted their own article within a topic.

More concisely:

[...] The author had violated the number one rule of good writing, the “Show, don’t tell� rule. There was not a single story in the book. It was chock full of sentences like “A good team leader provides inspiration by setting a positive example.� What the eff?

From "Introduction to Best Software Writing I"
By Joel Spolsky

http://www.joelonsoftware.com/articles/BestSoftwareWriting.html

I prefer books that stay on the topic and don't waste my time dumbing down to make it more readable. I'm interested in the information, and if I want to read stories, I'll pick up some real literature. Unfortunately, the reviewers and editor of the book I'm working on don't share that point of view, so I'm working hard to write in a style that I don't even like myself! Thanks Joel and friends! ;)