There seem to be two different types of technical writers. First, there are the good writers who know their topic fairly well and can clearly explain what needs to be explained. Second, there are the so-so writers who know their topic inside-out but can't clearly get the reader from novice to expert. One of the problems with being an expert is that you forget what it was that you once didn't know.
That is why I think teaching is very important for an expert. Being confronted by people who don't know the topic forces you to think clearly on how to explain things. Tapestry in Action is an example of this problem. The book is going to be read mostly by people who don't know Tapestry but the book doesn't take you from A to B to C but rather takes you from C to G to X. One of the causes of this problem is that authors don't get feedback until their book is in print unless they have excellent reviewers. The problem with some reviewers is that they can suffer from Stockhom Syndrome and begin to accept and support the author in their bad habits. Technical reviewing is a very difficult job and is certainly not for those unwilling to be critical.
I recall reviewing one book for Wrox which was a horror to review. I'm not sure if the authors were not native English speakers or they just cut all their English classes in college but they were unable to get coherent thoughts into properly formed sentences. I think the authors knew their topics but at times they seemed to be unable to show it. I tried my best to let the authors know that the book was spiraling out of control but they failed to respond and the completed book was not nearly as good as it should have been.
All this is as an introduction to Elliotte Rusty Harold's book, Effective XML. Harold is that rare writer who is both an expert on a subject and able to clearly explain that subject. Some of that no doubt comes from his being an adjunct profesor at a college in Brooklyn. Harold doesn't leave you wondering how he got to point C. He also doesn't use jargon or buzzwords just for the sake of using them. Right at the beginning of the book he clearly explains the difference between many of the common terms used in XML so that everyone is starting with the same lexicon. He also writes as someone who is eager to share his knowledge. I wish every book on technology was as enjoyable to read as this one.
The actual review is on my amazon review page.
No comments:
Post a Comment