A friendly exchange between an technical author and reviewer

by Robert Nagle on 12/20/2013

in Tech Writing

This fun thing is something I published in 2000 on my old site — and has since become dead. A mixed review of a famous book on programming prompts a reply from the author and a friendly
discussion about book reviewing

My Original Review (August 2000) about the book Mastering Regular Expressions by Jeffrey Friedl

I haven’t read the book from cover to cover but have read parts of it. I don’t deny that it is informative and occasionally helpful (especially if you come from a perl background). But the book as it stands is not appropriate for someone starting out in regular expressions. Instead it provides a lot of depth as far as how regular expressions are used in specific tools and all the different standards for regular expressions.

But a lot of this information on regular expressions is not relevant or necessary for composing plain vanilla bash regular expressions. I suspect that the majority of readers will find a few chapters helpful, but will skip over at least a few chapters that have no bearing on their work. To spend so much time in a book talking about the different implementations of regular expressions is to beg the question about whether you should read a general book or instead read a book about the implementation of r.e. specific to your computer language.

I have two complaints. First, the book does not try to teach you the art of writing regular expressions (it assumes a certain level of familiarity already). As a learning book, it may not be satisfy your needs. The second complaint is that the book doesn’t include an adequate reference section or at least a section you can refer to when trying to write your own regular expressions. I found myself flipping back and forth from pages to try to find the aspect of regular expressions I need. A more methodical reference chapter or appendix is sorely needed.

Don’t get the impression I am not recommending this book. It is a fine book; only be sure that you thumb through it at a bookstore to make sure that the kind of material it presents is what you are looking for. For me it was not. The best teaching book I’ve found to explain regular expressions is Practical Guide to Linux by Mark Sobell. It’s old, but it explains regular expressions, sed, awk and grep better than any book, including this one. This book presented the clearest examples of any computer book I have encountered.

 

The Author Responds (December, 2001)

This evening I noticed your review of my book “Mastering Regular Expressions” on Amazon. I’m sorry that you didn’t get out of it what you desired of it. Perhaps if you had more of a need for advanced regex use, it would have been more valuable.

In your review, you make two specific complaints. The first, “does not try to teach you the art of writing regular expressions”, makes me wonder what book you’re revewing. Teaching that art is the heart of the book, and the 100 or so pages that make up chapters 4 and 5 do nothing but teach that art. Perhaps they were part of what you didn’t read (you don’t learn an art by flipping around and reading tidbits like it’s a Reader’s Digest :-)

You also comment “(it assumes a certain level of familiarity already)”. Well, the later chapters assume you read chapter 1, which starts out from scratch.

I find your comments puzzling because as you said yourself, you haven’t read more than “parts of it”, so how can you make any claim about what it doesn’t do? Sure, I know it can’t be all things to all people, but you really knocked it right where I’m the most happy with it.

You’re right about your second complaint, though (needs a better reference section). My original thought was that I wanted to teach the thinking of regular expressions, and leave most tool-specific stuff to your tool’s manual. Why would someone want to pay for a copy of what they already have? But I find it’s a common desire, so in the 2nd edition I added 25 pages to Chapter 3 (which is really the lost child of the first edition), with a much expanded use of the “=> XX” page references that make the page flipping (which you can never eliminate) much more bearable. Anyway, I do hope that the book is able to prove its value to you sometime.

 I Respond to the Author (December 2001)

Thanks for your reaction. It is an honor to receive something from the author himself!

I write reviews of Oreilly books very often, and actually I request review copies from them every so often.

The first thing I should say is that I consider myself a nonprogrammer, and it’s quite common for me to write reviews of subjects about which I know absolutely nothing. I’m a technical writer and I focus more on the “readability” and organization of the book.

So I am writing as a nonexpert. And to be honest, I haven’t used regular expressions much, although I imagine that the time for that will come.

I remember reading the first few chapters (perhaps a little too breezily , I’ll admit), and enjoying them and finding the information useful. The examples were also very good. I just found the detail about the different engines overwhelming and not really relevant to my current needs. (For some people, this information may be the best part of the book,I”ll admit).

With programming books, one’s reaction to them changes over time. Some books I initially think are horrible, and then I find myself referring to over and over. With others, it’s just the reverse. Sometimes I feel I should write “updates” on amazon about what a numbskull I am.

So please don’t get the impression that I was panning the book.

Regex is such a broad subject, and every programming language seems to have their own quirks. The changes you mentioned sound interesting and could probably make an excellent book even better.

On another note about not reading,etc. An anecdote. My friend (a professional book reviewer) often would choose books to review on the basis of how little reading was required to actually write the review. On some books, he wrote the review while barely opening the book! While this seems dangerous, sometimes initial impressions can be helpful.

The Author Responds to my Response (Dec 2001)

I’m not so sure that one should consider an email from me to be an honor — most of my friends procmail me away :-)

I appreciate your detailed reply, Robert, though I still feel that your review is unjust. It’s not that it says negative things (for certainly, any book can’t be all things to all people, nor even do what it intends to do perfectly). It’s that I feel that *had* you used the book as it was intended (and as the preface — the book’s instruction manual, so to speak — suggests), your concerns would have been answered and your review would have more accurately reflected the contents and usefulness of the book. (Such a review certainly may well have included negative comments that came with your deeper knowledge of what you were were reviewing — I know that the book is far from perfect.)

I’ve seen a few negative reviews of my book over the years that have basically said “I wanted to book to be X, and it wasn’t!”. In every case, “X” was something that the book was not intended to be, so while I wish the reviewer had had a better experience with the book, such a review does serve a purpose to clarify to the reader of the review what the books does and doesn’t do.

I guess what it comes down to is that if one feels the needs to begin a review with “well, I’ve not really read this book”, I feel one probably shouldn’t be offering a review at all. I realize that putting out more reviews gets you brownie points at Amazon, but it’s really not fair to me or to your readers. At least, that’s my feeling.

Regex is such a broad subject, and every programming language seems to have their own quirks.

Ha, if you still have a copy of the book, see the first sentence (and footnote) of the last paragraph of p62 :-)

If you thought my book was “excellent”, your review very much does not give that impression. It gives the impression that the book is very bad at doing exactly what I belive the book is best at doing (bringing a novice up to speed, and teaching the *art* of writing a regex). As it’s written, I belive your review does a disservice to me and to all the readers of your review.

I’m aware that there are people who do their job poorly. It’s sad, in any field, and all the worse when it hurts others. I try not to do mine here at Yahoo poorly, nor mine as an author. (My overriding principle when I’m writing was given to me by an author friend who said “you do the research, so your readers don’t have to”. People are paying *their* *money* for my book, so I’ll be dammed if I’m going to give them anything but my very best effort.)

The 2nd edition concentrates mostly on the popular scripting languages (VB and other .NET Framework languages, Java, Perl, Python, Ruby), and less on the old Unix tools (awk/sed/lex). If it happens to land on your desk, I hope you find it useful.

A Friend Makes a Very Valid Point (Dec 2001)

Bobby, this is very interesting/amusing to read. I don’t recommend responding to him again, but perhaps you might have clarified that the books I choose that “require the least reading” are either 1) books with very little text to read, 2) reissues of books I’ve read before, 3) anthologies of literary material that I’m often already familiar with, or that only require a sampling of stories to be read for a broad impression, or 4) reference encyclopedias that are not meant to be read cover to cover, but which have certain important entries. He might think I idly try reviewing technical things I have no knowledge of. Actually, it’s my prior knowledge of a subject that enables me to review certain books quickly without much effort.

(Now it can be revealed; this critic/friend is Michael Barrett, book and movie critic extraordinaire!)

I Become Philosophical (August 2002)

I am very sympathetic to this author’s defensiveness about his book. One has only to look over the hundreds of rave reviews on amazon to realize that the book is one of the most praised books on publishing today. As Andy Oram writes, “Yet Mastering Regular Expressions came out and became an instant hit. The Perl community (where regular expressions had taken hold most strongly at the time) treated Friedl as a hero. His talk at the first O’Reilly Perl Conference filled a large hall right up to the back doors. We sold out all copies of his book at the conference, even though it had released six months before, and brought in another batch of copies that were promptly sold out as well. Five years after publication and 22 years after the death of McLuhan, the first edition still sells several hundred copies per month and is continually recommended on mailing lists and in journal articles.”

During the year 2000 I reviewed lots of books that I only half-understood (or at least wouldn’t be able to really understand until I tried it out myself). Often one’s gut instincts about a book are right; sometimes they are not. Sometimes a book which didn’t seem user-friendly at first turns out to be exactly what you need. Conversely, some books which look useful may in fact be too simple or too esoteric to be useful.

So I went back to the book and read a few more chapters, afraid that I had seriously misjudged this book. Well, surprise, surprise! I not only stood by my previous opinion, I found myself justifying my original decision to review a book I hadn’t read all the way. To review a technical book requires, in all fairness, that you read the book from start to finish. That seems like an obvious point, but it is completely wrong. It overlooks the fact that reviewing is often about reporting what the book contains and doesn’t contain. With technical books, how do you criticize? You are reading a subject that you are probably a novice at, and the author is certainly an expert. Aside from pointing out technical errors (and from what I’ve heard, all technical books seem to have their fair share of them), the critic can talk about writing style, logical approach to the subject and whether the book covered the subject in a way that newbies could understand. My original review was not delivering harsh criticism to the book really; it was merely suggesting some reasons why this particular book might not be useful for some people.

As a matter of fact, Friedl has a nice breezy writing style that is a delight to read. And indeed, it looks like a novel—the book is full of prose. Chapters 4 –the real crux of the book–gives a step-by-step guide to solving problems using regular expressions, explaining the syntax and showing some great examples. Chapter 5 is about optimizing, and the rest of the book hovers on the topic of Perl. My main problem was and still is that I couldn’t find what I needed whenever I picked it up! In contrast, whenever I wanted help on deciphering or writing regular expressions, I found myself referring to the much simpler “ Practical guide to Linux” .The author admits as much in his initial response that the first edition lacked an adequate reference section, and it seems likely that the second edition will address that difficulty.

While Mr. Friedl has every right to respond to his critics, I have to wonder whether he is a shade too indignant. No book can win over everybody. Even if a book comes close to achieving that, it will no doubt attract a crowd of critics eager to deflate the hype, to burst the bubble, to rain on the parade. Of course, I intend to do no such thing. But amidst a chorus of lavish praise, the temptation of a critic to inject a modicum of dissent becomes irresistible.

Leave a Comment

Previous post:

Next post: