The second printing is on Monday August 4th. Already! I think the book has been selling a lot better than anticipated. I know I am psyched to see it remain in the top couple thousand on Amazon. And they thought it was a big deal when it broke five thousand!

In other news, it’s going to be translated into Spanish, Polish, and Portuguese. So now all my friends in Brazil will be able to read it in their native language.

And Percona’s two expert consultants in Poland, too. No undue influence was exerted. I didn’t even know it would be translated. Really! We do have a Spanish-speaking consultant who lives in Spain, but he is a native English speaker. Now, all we need are Russian, German, Lithuanian, and Ukrainian translations and I think we’ve pretty well got the company covered, at least until we hire again.

Related posts:

1. An ongoing thread of blogs on MySQL performance In the las
2. Cary Millsap: Thinking Clearly about Performance Cary Mills
3. A review of Optimizing Oracle Performance by Cary Millsap Optimizing

Related posts brought to you by Yet Another Related Posts Plugin.

I just finished reading Building Powerful and Robust Websites with Drupal 6 (this title on Packt’s site). I’ve been working on a website powered by Drupal, and though it was obvious that Drupal is very flexible and capable, I was getting pretty lost in the website. So I wanted to read a book that would explain it to me.

Unfortunately, this book didn’t help me much. I’d give it 2 out of 5 stars.

Overall the content of the book is not about what the title promises. In fact, I’d say the title ought to be something like “an introduction to…” or “basic concepts with…” instead. Unfortunately, these titles don’t really capture the spirit of the book either. It’s hard to actually explain what the book is about, and I think that’s its main problem: the book has an identity crisis. It can’t decide what it is really trying to say, and thus it seems to go from one topic to another without a really strong direction. (It does have some direction and organization, but it could be stronger.)

As a result I now know almost nothing about Drupal that I didn’t discover by trial and error over perhaps 8 hours or so working with a live site.

The book is 380 pages and I think it ought to be a lot shorter to cover the material it covers. The writing is far too wordy, so whole paragraphs sometimes end up saying nothing at all. For example, “reduces the amount of work required later down the line” should just be “saves work later.” A lot of what’s included is just irrelevant. For example, the preface spends a lot of time telling me that the Internet is an exciting revolution, yada yada:

The Internet is arguably one of the most profound achievements in human history. It has become so pervasive in our lives that we hardly even notice it—except when it happens to be unavailable! It’s one of those things that make you sit back and wonder how people got along without it in the old days. Without the ability to surf the Internet to order groceries, do our banking, book flights and make travel arrangements, meet friends, meet partners, download music and videos, study, run businesses, trade shares, run campaigns, express views, share ideas, learn about other people… where would we be?

There’s a lot of that throughout the book, unfortunately. See if you can understand this:

Chapter 8 gives you a run down of how attractive interfaces are created in Drupal through the use of themes. As well as discussing briefly some of the considerations that must be taken into account when planning your website and ends off by looking at how to make important modifications to your chosen theme.

And on page 4: “little to now experience…” and later, a really confusing one: “How you deal with file system settings really depends on what type of content you use to visualize your site.”

The typesetting is also hard to read. For example, it’s set ragged-right, but even worse, there are many places where lines are broken far shorter than they need to be. It looks to me like they just put Word documents onto paper with no real typesetting.

When the content actually picks up momentum, it covers a bunch of things I could do without, such as explanations of what open source is, and Drupal’s licensing. As I said, this book has an identity crisis; these are important topics, but not in this book.. In chapter 3, I begin to see some stuff about how to use Drupal. But then it jumps right into how to set up forums. Unfortunately I really missed explanations of the concepts. The concepts are too intermingled with the examples, which I didn’t understand because I was only reading the book, not actually working through the examples. I got lost very quickly and never found myself again.

This book is not skimmable to get info at any level other than following along with the author — I mean, installing your own copy and literally performing every action the author performs so you can see it in action. For example on page 69, there’s a lot of talk about containers — and then it says “click Add container to bring up a page…” wait, I thought that’s what we were doing already? I’m sure I read it wrong, but unless I’m willing to build myself a website on my laptop to follow along, I can’t tell. I really wanted the book to explain things to me without making me work through the examples. I’m sure it’s hard to do, but it must be possible.

At the end of each chapter, there’s a summary. They are too congratulatory. “This chapter provided a good grounding in the basics of controlling access to your site’s content.” I disagree. Then later, “From learning about what considerations must be taken into account when planning a website’s look-and-feel, to making changes to the code, this chapter has provided a firm grounding in the fundamentals of working with Drupal interfaces.” Again, I just didn’t get that out of it when I read it.

So what was I looking for from the book? I wanted to understand what Drupal’s special lingo means, really. I mean, if you’ve worked with Drupal, you’ve seen all the words it reinvents for its own special uses — taxonomy, hierarchy, term, vocabulary, node, field definition, content type, and on and on. Each of these means something really particular in Drupal — not at all what we mean in common English. I am still confused about all this: what each of these things really is, how each relates to the other, why I see them in various contexts, when I should use one instead of another, and so on.

In summary, I’d say that I’m now even more convinced that Drupal is almost ridiculously flexible and powerful, but this book just didn’t help me much. It is a noble effort but alas, I needed more from it.

PS: some people have asked me about the grammar rules and regular expressions I used while writing my own book. This book is a great example of how specific those are to my own writing. If I were this book’s author, I would have a rule to catch “make use of,” “head on over,” and “go ahead.” There is also a lot of “of course” that substitutes for a real explanation on topics where I really wanted more help understanding.

Related posts:

1. Writing a book about Maatkit I’ve
2. A review of Pentaho Solutions by Roland Bouman and Jos van Dongen Pentaho So
3. A Review of Beginning Database Design by Clare Churcher Beginning

Related posts brought to you by Yet Another Related Posts Plugin.

The book fluctuates between sales rank 1000 and 2000 on Amazon during the day, and has reached as high as 600 or so. This is just phenomenal. The O’Reilly team was psyched when it broke 5000, and so was I — but now we’ve stayed under 2000 for a long time (except when Amazon sold out of it). Frankly I’d have thought that for a niche-market book like this, we’d have been in the 10,000 range or something like that.

Clearly we (the authors, editors, publisher, etc) have done something right! This is a great feeling.

Thanks for sending errata, by the way. I have just completed proofreading the whole book myself, and found a number of things that may be fixed in the second printing. I think certain types of errors won’t be fixed, but the important ones certainly will be.

Related posts:

1. An ongoing thread of blogs on MySQL performance In the las
2. A review of Optimizing Oracle Performance by Cary Millsap Optimizing
3. Sessions of interest at the Percona Performance Conference Having wri

Related posts brought to you by Yet Another Related Posts Plugin.

Don’t tell my wife this, but a book is never done.

Right now I’m proofreading the printed copy. I proofread PDF after PDF during production, but some problems will always slip through and make it to paper. I’m finding quite a few little mistakes. For example, at one point we refer to TPC as TCP three times in a row. Oops.

These problems will be corrected in the next printing. Please notify me if you find any errors yourself, and I’ll add them to the list of things to fix! Also let me know if you find things that should just be “fixed” in general. For example, the layout and page-breaking on pages 364 and 365 is totally confusing — it’s hard to tell which figures are associated with which text.

I’m not offering rewards like Donald Knuth, sorry…

I will place a list of errata on the official High Performance MySQL Second Edition website, including a non-mangled Figure 8-12. (Another thing that didn’t make it through production unscathed.)

Related posts:

1. A review of Optimizing Oracle Performance by Cary Millsap Optimizing
2. An ongoing thread of blogs on MySQL performance In the las
3. Cary Millsap: Thinking Clearly about Performance Cary Mills

Related posts brought to you by Yet Another Related Posts Plugin.

Was I fair, balanced and honest?

I really intended to write the post as just “here’s what it’s like, just so you’re prepared.” But at some point I got really deep into it and lost my context. That’s when I started to write about the things that didn’t go so smoothly with the publisher, and some of these things had a little extra sting in them that I would have done well to edit out.

All of us are human and the process wasn’t that bad, all things considered — the book was just a massive project that put huge demands on all of us and stressed everything from the capabilities of our chosen tools to our patience. As the editor points out in his response to my blog post, this is precisely why nobody else has ever been able to pull this off. This book stands head and shoulders above the crowd. It’s just hard to write, and very few people in the world actually have the knowledge to do it, much less the time, inclination, and ability.

Everything I said was (I believe) factual and correct, although as the editor points out there are different stories behind them. I also want to mention that I’d shared all those concerns with my editor; I avoid criticizing people behind their backs. In hindsight, throwing all of my concerns onto a blog post without warning isn’t the kind of thing I like to do either.

So I believe I was honest, but unfair to the editor. I’ve apologized to him. And by the way, yes I would work with him again, and I fully expect that it would be easier because I have learned more about the process.

I ran this post by my editor before publishing it.

A deeper explanation of my heuristics

Several people asked me to say more about my heuristics for improving the quality of the writing. I’ve already explained many of them, but here’s more:

(were|was|is|are|has been|be)( [a-zA-Z]+)? [a-zA-Z]+ed\>

This regular expression can help find some occurrences of passive voice. It finds a word or phrase that’s some variation on the verb “to be,” usually in the past tense; followed by an optional word (probably an adjective); followed by another word that ends in “-ed,” which is also potentially a verb in the past tense. This is not the only way to write in the passive voice, but it’s kind of the classic. Here are some examples: “the blog post was posted,” “the benchmark was rapidly created.”

(were|was|is|are|ha[sd] been|be)( [a-zA-Z]+)? [a-zA-Z]+e[dn]\>

An enhanced version. As I looked at the preceding point, I saw some other simple examples it doesn’t catch. For example, it doesn’t catch “had been” and it doesn’t catch verbs like “written.” Ironically, the first thing that came to mind as I thought about examples was “the book had been written.”

while|since

There’s nothing wrong with these words, except when they’re used in lieu of “because” to indicate causality. This is a problem for non-native English speakers, because these words have a temporal meaning too. For example, “Since MySQL 4.1 has no stored procedures, you have to use MySQL 5.0 if you want stored procedures.” If you aren’t a native English speaker, and even if you are, it’s easy to read that as “MySQL has had no stored procedures since version 4.1, …” and then when your eyes reach the part about MySQL 5.0, it makes no sense. My rule for this is to say “because” when I mean “because.”

using

Real examples: “Using MyISAM tables works very well” can become “MyISAM tables work very well.” And “A final possibility is simply to switch to using a table” can become “Finally, you can use a table” instead.

in order

The phrase “in order to” can almost always be replaced by “to.” It also tends to show a rough transition between the first and second phrases in a sentence. Perhaps these phrases should be integrated into a single phrase. “You can use this regex in order to find poorly constructed sentences” can become “this regex can find poorly constructed sentences” or “You can find poorly constructed sentences with this regex.” I prefer the latter; it is very direct, and that straightforward, simple writing style is really important in complex subject matter.

of course|without saying|obviously|clearly|needless

It goes without saying, but of course these words obviously point out when I’m writing stupid things that I clearly need to take a closer look at. Needless to say, most of the phrases in this paragraph are indeed needless to say. They are a red flag for lazy writing, such as glossing over a difficult point that should instead be explained — hard work, but necessary.

whether

I found quite a few places where the phrase “whether or not” was used. This can be shortened: “to see whether or not the disk is the problem” can become “to see whether the disk is the problem.” But better yet, the phrase often glues together poorly written phrases into an awkward sentence, just as “in order to” does. Can “whether” be replaced by “if?” Or does the sentence or paragraph just need to be reworked completely?

allow

This word can usually be replaced by “let.” “The remaining settings allow MySQL to allocate more RAM” can become “The remaining settings let MySQL allocate more RAM.” Occasionally, it is part of a larger phrase or thought needs to be shortened and clarified. “When nobody is writing, readers obtain read locks that allow other readers to do the same” became “When nobody is writing, readers can obtain read locks, which don’t conflict with other read locks.”

ensure

I found that this word is often subtly misused. It really means “guarantee” but is often used as “double-check” or “make sure.” I don’t want to be too dogmatic about this word: its usage in modern English is complex (see the usage note on assure here; that in itself might be a reason to avoid it). But I found many places where I wanted to remove it in favor of an explicit instruction that tells the reader to take action. “Ensure” as an instruction is kind of a politically correct way to tell someone to do something, and I’m not afraid to just tell you to do it if I think you need to. I don’t want you to miss my meaning.

only

I have a habit of using this word incorrectly. “I only have ten fingers” should be “I have only ten fingers.”

as (we|you)|again,

These phrases usually show a place where the writing is confused and redundant. They show up in places like “as we already said, you should tune your server” and “again, you should tune your server.” Any instruction to the reader to break the narrative flow is a place to examine whether the concepts are in the right order. Cross-references, footnotes, and reminders are not always evil, but they’re to be regarded with suspicion.

Readability metrics

The tools I used to find sentences and phrases that score badly on some readability metric were pretty helpful to me as I tightened the writing up more and more. Nobody has reviewed the book yet, but I think when they do, they’ll be unlikely to mention “oh, and by the way the writing is wonderfully compact!” If we pulled this off right, you won’t notice that the writing is clear and compact. Writing is like a stereo system: you’re supposed to hear the music, not the speakers.

Anyway, my point is that we expanded the first edition’s actual coverage many times over, and ended up with only 658 pages of actual material. So the writing is much more compressed, and to do that you have to find and eliminate confusing writing. Confusing writing usually means that the concepts don’t flow clearly, and it takes more words to say the same thing because you’re kind of bumbling about, gesturing at your meaning from several angles instead of saying it clearly just once.

Here’s how I analyzed each chapter:

• I used OpenOffice’s export feature to export the file to MediaWiki format. This is a plain-text markup format. I forget now why I didn’t just export to text, but there was something about MediaWiki format that made it easier to munge with Perl.
• I ran my clean_text.pl program against the exported file to convert the format to a simpler one without special characters and markup. Some of the markup (footnotes, for example) stayed in the text and confused the metrics, but that’s life.
• I ran my analyze_text.pl program against this to find the “worst” places.

As I wrote in my previous post, the analyzer uses a combination of readability metrics and “other stuff” to measure the badness of each sentence and paragraph. It aggregates sentences and paragraphs by the metrics. I calculated the number of words, percent of complex words, syllables per word, number of sentences, words per sentence, and a bunch of other things, as well as the standard readability metrics. Each sentence and paragraph got scored on these. Then I printed overall metrics, and sorted the sentences and paragraphs worst-first and printed out a snippet of the offending text. Here’s a sample of chapter 3’s metrics (originally numbered chapter 4) at some intermediate stage in the writing process.

This was a lot of work. If I had been writing with Vim, I could have done better. I could have used the compiler integration and set my “make” program to the analysis program. If you use Vim and you don’t know about this, it’s a pity. My next book will be written in Vim, by the way.

Actually, I probably could have done better regardless, but this was good enough. I just searched for the snippets and then examined what was going on.

There were some false positives. For example, bullet-points often scored badly on the readability metrics, and so a five-word bullet point item would look like terrible writing just because it was short enough that it had a high percentage of complex words. It’s not an exact science. Maybe next time will be better.

If you’d like to see the source code, here’s the clean_text.pl and here’s the analyze_text.pl. Enjoy!

Related posts:

1. Writing a book about Maatkit I’ve
2. How to write a good MySQL conference proposal I’m
3. How to write to a Perl variable as if it’s a filehandle This is re

Related posts brought to you by Yet Another Related Posts Plugin.