That's my feeling exactly. Too often the manuals and documentation people read are a chore to get through because they're so boring. They're also passive aggressive because they're obviously saying their technology is better in some way, but they're trying to be nice. You read through and there's little lame attempts at being the next Oscar Wilde when really it'd be much better if they just came out and started a fight.
When I write my docs I want it to teach people how to use it, and not put them to sleep at the same time.
Let me clarify what I mean. Zed usually takes this approach: "Here is something that idiot programmers do; let me show you the right way."
Half his audience will read this and think, "Gee, I don't want to be an idiot--I should continue reading!". The other half will take it as an insult, or just find it to be in bad taste, and put the book down.
A good writer should be able to get across his message without insults.
A good writer entertains readers and makes them think while getting his point across. Boring writers try to not offend anyone.
Thats so true. When I wrote my book, most of my battles with O'Reilly was over 'toning down' of my content.
O'Reilly was great to work with but they were a bit worried about offending people. When the book released, it worked out great - people loved it.
Re:Zed Shaw completes mongrel2 manual
by stcredzero on Friday July 30, 2010 @11:33AM
(#1561439)
Actually, he'd make a fantastic tag-team with _Why. It would be a little like Abbie Hoffman & G. Gordon Liddy on the same speaking tour. Not to say these guys are on analogous points of the political spectrum (couldn't care less) but that they have markedly different points of view and would have a very interesting antagonism.
I have no idea how those two would ever co-write a book though. I bet that would sell, however.
What you need is someone with decent taste to say this sucks, that's cool, here's why.