Noel Rappin Writes Here

It’s not much of an exaggeration to say that I’ve been writing the same two or three chapters for six months. I think — I hope — this is the last time.

This is a more or less weekly update on the manuscript currently known as Master Space & Time in JavaScript. Today, the update is about the first few chapters and how they change over time. These chapters cover a lot of ground, and getting the order and beats right has been a struggle. But I think I’ve got a good handle on it now.

(If all you want is a pure update: I’m making progress. The biggest factor in when the book actually goes on sale is how much I decide to have completed before I sell it. But I think we’re still looking at a few weeks out.)

The problem with the first couple chapters is that there are a lot of topics to cover right at the beginning. The first part of the book introduces jQuery, but I also want to introduce testing as a practice, so Jasmine comes in immediately as well. I want to use the examples in the book to model a good test-first practice (for the two or three of you that are familiar with my Wrox book, you know that I tried something similar there).

However well intentioned my plan to cover testing is, the fact is that for a reader unfamiliar with both, simultaneous exposure to Jasmine and jQuery has a lot of potential to be confusing.

In my first draft, the reader was presented with a suite of three or four Jasmine tests, which were fully explained, then with the jQuery code. The example is super-simple — just making a detail show and hide based on a user click. That’s on purpose, so nobody gets bogged down in the details of the example. Even though it’s simple, it does touch on a lot of basic jQuery features, which were explained in some detail, while also referring back to the Jasmine.

Some early reviewers found the back and forth confusing, so I tried a few different ways to clean it up:

• I really like starting books with quick demos that show off things that will be fully explained later. So I added one that covered the JavaScript console. More on that in a moment.
• I added a lot of text explaining exactly where the reader was, why we were talking the thing we were talking about and so on. A lot of this was necessary and stuck around, though at one point I wound up with a two-page chapter introduction that was — accurately — described as “apologetic”.

Eventually, though, I tried to separate the chapters, presenting the jQuery code first and then the Jasmine tests after. On the plus side, separating the two led me to write much better explanations of each library. On the down side, the order just felt really wrong to me, it wasn’t really the way I wanted the book to go.

As I tried to bring the material together for the new version, I came up with an answer that I think keeps all the draft material I like, and scraps the stuff I don’t. I mentioned that I really like quick-march introductions for my books. It finally occurred to me that the small example actually works as a quick introduction. So the plan is to work through that example in a kind of strict test-first way, showing the rhythm of a BDD process without a lot of library detail. Then go back and describe Jasmine in more detail, then jQuery in more detail.

Which makes this the current table of contents:

• Introduction. Mostly logistics, explanation of what’s there and so on.
• First Look: The quick walk through Jasmine and jQuery.
• Jasmine in more detail.
• jQuery in more detail — at least the basic selector and element manipulation parts.
• JavaScript functions and objects. How they work. We take the simple code from the first example and apply different JavaScript module and class patterns to it. I like this chapter.
• Developer tools, the console and the WebKit package
• Pulling the first few chapters together on a more complex example — a multi-select autocomplete widget.
• Ajax. How to do it and how to test it.
• JSON. This is an Amazon-style rating widget, so pulling in everything so far plus Ajax, plus JSON.
• Backbone. Probably 2-3 chapters here, covering Underscore, and Mustache. This is the point where we get to things that haven’t been written yet, though I do have an outline.
• Depending on how ambitious I feel at this point, a similar treatment of Ember.js is possible.

The initial release is most likely everything up to the JSON chapter, thought it’s possible I may start putting it out there once I finish reworking the autocomplete widget chapter.

If this sounds interesting to you, let me know by signing up. There’s still time to suggest other tools you want covered. Or leave a note in the comments here.