Rails Test Prescriptions Blog

Keeping Your Application Healthy Since 2008

Category Archives: Me

Self-assessment

Here’s what I’ve got.

2 chapters introducing jQuery and Jasmine via a walkthrough of a simple piece of JavaScript functionality.

1 need to convert all my text from its current proprietary format to something more Markdown based.

1 genuinely silly conceit tying together the application that gets built in the book. And I mean that in the best way. It should be silly, there’s no reason not to be bold. There is even a twist ending. I think.

1 slightly dusty self-publishing tool chain that converts a directory of markdown files into HTML, with syntax colored code. It’s possible that there’s a better library for some of the features these days.

1 chapter on converting that simple piece of jQuery into various patterns of JavaScript object. I quite like this one, actually.

1 website, which is currently hosted by WordPress – at one point, I had to abandon the railsrx.com site that actually sold stuff, and WordPress was easy. I think I’ll need to upgrade that a bit.

1 Intro chapter covering JavaScript basics and the Chrome developer tools. Not sure if this is at the right level for the audience I expect.

1 Prince XML license for converting said HTML files into PDF. No idea if that’s still the best tool for the job. Or even if my license is current.

1 chapter on building a marginally complex auto complete widget in jQuery and Jasmine. I like this example.

1 copy of most of the book’s JavaScript code in CoffeeScript. Not sure when I thought this was the right idea for the book, beyond an excuse to use CoffeeScript.

1 chapter on jQuery and Ajax.

0 toolchains for generating epub and mobi files. I know I can find this.

1 case of impostor’s syndrome, not helped by rereading the harsh review of Rails Test Prescriptions on Amazon. That was dumb, why would I do that?

1 chapter on using JSON. As far as I can remember, this chapter never went to edit.

3 people who mentioned on Twitter that they’d buy a self-published book. Don’t worry, I won’t hold you to it.

1 plan for writing 2 or three chapters on Backbone.js

5 people who reviewed the last version who I feel should get free copies when this comes out. It’s not their fault.

4 viewings of Ze Frank’s “Invocation for Beginnings”

So. Ready to go. Watch this space.

Advertisements

A Brief Announcement About A Book

So… The JavaScript book that I had contracted to do with Pragmatic will no longer be published by them.

I need to be careful as I write about this. I don’t want to be defensive – I’m proud of the work I did, and I like the book I was working on. But I don’t want to be negative either. Everybody that I worked with at Pragmatic was generous with their time and sincere in their enthusiasm for the project. Sometimes it doesn’t work out, despite the best intentions.

I haven’t spoken about this project publicly in a while because it was so up in the air. And also because I’m not sure what to say about it without sounding whiny or mean. And also because I was afraid of jinxing things, which is obviously less of an issue now.

Since November, the book has been in review and I’ve gone through a few cycles with Pragmatic trying to get things just right. The issues had more to do with the structure and presentation of the material then of the content or writing itself. I’m not completely sure what happened, but I think it’s fair to say that the book I was writing did not match the book they wanted in some way or another.

Anyway, that’s all water under the bridge. I have full rights to the text I’ve already produced. Self-publishing is clearly an option, though the phrase “sunk costs” keeps echoing in my head. It’s hard to resist the irony of starting with a Pragmatic contract and moving to self-publishing after having done it the other way around with Rails Test Prescriptions. I’m hoping to blog more – in addition to being a time sink, not being able to write about this book was kind of getting in my head about any blogging.

Thanks for listening, and watch this space for further announcements. I was excited about this project, and while this is disappointing, I’ll be excited about it again in a few days. Thanks to the people I worked with at Pragmatic for the shot, and thanks to all the people who have been supportive of this project.

Coming Soon: Getting Things Done In JavaScript

Okay, the blog has been very quiet for the last month or so. Please be polite and pretend you noticed. I’ve alluded online to a new book one or two places and now I think it’s far enough along that I can mention it in public without being too scared.

Let’s do this Q&A style, call it an infrequently asked question list…

Q: What’s the new book?

A: Great question. The working title is Getting Things Done In JavaScript. That may not be the final title. My proposed titles, Enough JavaScript to Get By and JavaScript for People who Hate JavaScript were (rightly) deemed unsuitable.

Q: Okay. That’s the title. What’s the book?

A: Here are some excerpts from my proposal:

  • The intended audience are developers used to doing back-end development, probably but not necessarily in Rails, who are increasingly asked to move functionality to the client, and are not familiar with the best JavaScript tools available for the job.

  • This book is aimed at developers who are explicitly working on front ends for web applications and looking for guidance on how to approach the simple parts first and the complex parts as needed. In my head, this is triangulated with three non-JavaScript books that I think are around that level: Beck’s Smalltalk Best Practice Patterns, Olsen’s Eloquent Ruby, and Valim’s Crafting Rails Applications.

  • Everything is test-driven. This book will contain more Jasmine than a Disney princess convention.

Does that help? Put another way, it’s the JavaScript book I wanted to hand our last apprentice when he asked for a good guide to JavaScript. Another way I’ve described the audience is people who have poked at JavaScript a few years ago, just got back into it, and aren’t quite sure why everything is an anonymous function these days. I’ve also called it JavaScript: An Idiosyncratic Guide, as in the thing you use after you have the information in the definitive guide.

Q: Why a book on JavaScript?

A: Because I was a guy who poked at JavaScript a few years ago, just got back into it, and wasn’t quite sure why everything is an anonymous function these days…

Well, that’s part of it. I felt like it was an area where I had something to offer, and where I could leverage the time that I had spent getting back into the latest and greatest JavaScript tools and make it easier for others to do the same.

Q: When can I buy it?

A: The initial draft is maybe 1/3 done. Ish. The hope is to get it available in beta sometime in November, and given the schedule that Pragmatic likes for books these days, to have the final come out something like January. That’s still an aggressive schedule, and I’m probably just a smidge behind, but I have a decent idea where I want it to go, and I’m making steady progress.

Q: What’s actually in the book?

A: The outline is still a bit in flux, but the basic idea is to take a pure server-side application and bit-by-bit move features to the client-side in a slow and not-even-a-single-tiny-bit-contrived way. The JavaScript topics are largely focused on creating what passes for objects, so there’s discussion of the object model, functions and scope, and the like – it’s not (at least at the moment) a tutorial on the basics of JavaScript. There’s a lot of jQuery, and a lot of Jasmine, and there will also be jQuery UI, jQuery Mobile, and Backbone.

That’s the story. Coming soon to a theater near you. Hope you like it.

What I Learned

As you may have heard, Obtiva got bought by Groupon. I’ve been traveling a bunch, so this coming week is my first full week in the Groupon office post-transition. And, well, someday maybe I’ll write retrospectively about Obtiva, but today isn’t that day. I’ll probably write about what I’m going to be doing at Groupon, but today isn’t that day, either.

Instead, I realized that month marks four years since I left Motorola and became a Rails consultant. In that time, I worked, for some definition of worked, on over a dozen projects and probably watched at least another dozen from down the hall.

I must have learned something, right?

I finished out this post, so I guess that means that yes, I do think I learned something. Here are a dozen or so oversimplified, fortune cookie-esque things that I think I learned in the last four years. Some of these are probably blog posts in their own right, which I may get to one of these days.

  • It’s a hallmark of successful engineering teams that they understand that if you do not need to make a decision, then you need to not make a decision. That’s sometimes called “preserving ambiguity”, and I remember from back in my days studying engineering education that it’s a hallmark of successful engineering teams across disciplines.

  • One reason why preserving ambiguity is necessary is that if you get too concrete too soon, then early decisions have a kind of gravity that makes it hard to escape them even when it’s best to explore the problem space more fully. A couple of times in the last four years, clients have come in with polished visual designs, and even if the layout and structure doesn’t work at all from a functionality or usability standpoint, it’s hard to escape the concreteness of the design to find a better design or a better definition of the project.

  • There’s very little that damages a team dynamic more quickly than trying to measure and compare individual contributions. (Technically, I learned this one at Motorola, but it still applies…) On a larger project, measuring subteam contributions also qualifies as problematic.

  • One thing you absolutely must have when coming out of your initial project meetings is a list of things that are not part of your project. Again, a common client pattern was trying to be the “YouTube of X” and the “Facebook of X” and the “Twitter of x”. Pick something to do well and do it well.

  • You can’t escape the software triangle, of scope, budget, and schedule. Keeping a project on track means saying “this is out of scope”, or “okay, we can do this, but that means something else needs to move out of scope”.

  • Hiring is so, so important. I once heard it said that the secret weakness of Agile was that one sociopath could ruin an entire project. That doesn’t mean “just hire your friends”, but it does mean that being able to work as part of a team is important.

  • If the business/management team and the development team trust each other, than almost any process works. If they don’t, almost nothing can fix it. One advantage of Agile methods is they provide a lot of quick, easy, and early opportunities for each side to show trustworthiness. (There’s definitely a longer post in this one…)

  • Because, ultimately, for a lot of our clients, working with developers is like going to the mechanic. When the mechanics say that the fitzelgurbber has been gazorgenplatzed, and it’s 500 bucks, do you trust them? Why or why not? How do you apply that back to your day job?

  • The development team’s job in an Agile project is to honestly estimate the cost of things, it’s the business team’s job to honestly estimate the value. Don’t cross those streams. It’s bad.

  • Agile is about managing change, not continuous change. If anybody on your project tries to justify a change with something like “we’re agile, we can change anything whenever we want”, run for the hills.

  • I didn’t say this, but I remember hearing it a few years ago. The right amount of process is just a little bit less process than you need. In other words, the slight chaos from too little process is much preferable to the overhead of too much process.

  • Look, I’ll admit that those of us that identify as software craftsmen sometimes get overly precious with our naming conventions and of course delivering business value is the number one priority. That said, if you are on a project and are being told to do less than your best work for the good of the project (by not testing, or by incurring too much technical debt), that should at the very least be alarming.

  • Pair programming has more overhead than is often acknowledged in Agile literature. I find that, especially on a small team, keeping a pair in sync time-wise is very hard. That said, I don’t have a better solution for code review yet.

Can’t wait to see what I learn this year. A lot of new stuff for me, should be interesting.

Bill James, Sabermetrics, and You, or At Least Me

I was a nerdy kid.

I suppose that isn’t much of a surprise, given how I turned out. But in those pre-computer days, I was nerdy about math and baseball. I was the kind of kid that kept a daily log of my batting statistics in the recess kickball games.

So you can imagine my surprise and happiness when this image appeared in Sports Illustrated, in May 1981. I was ten:

Bill James in Sports Illustrated

The man in the foreground is Bill James, who would soon go on to be one of the most influential baseball writers of the last thirty years. At the time, though, he was self-publishing his baseball book to a small but fiercely loyal group of fans, one of whom actually wrote the SI article.

In the background, on the scoreboard, was one of James’ inventions – a formula called Runs Created that purported to be the most accurate way to measure a baseball player’s contributions.

Okay, I’m getting carried away. The relevant point is that I was dazzled enough by the original article to start looking for James’ annual book once he started getting published and distributed nationally. As I said, I was young, and the books cost like seven dollars of my own money, so this was kind of a big deal.

I got lucky in my choice of baseball writers. Not only was James iconoclastic and funny, but he was very good at explaining his methods. And I don’t mean that he was good at explaining the math – James is the first to admit that he is no mathematician (admittedly joking, he once described the “standard deviation” of batting average as “about what your standard deviant would hit”). James’ skill was in explaining why he did his experiments in a particular way. In a very real way, the most important things I learned about how science works were from reading Bill James.

In, I think, the first book of James’ that I read, he responds to criticism of earlier work:

“Journalists start with the answer… [Sabermetrics] starts with the question”

Sabermetrics, by the way, was the word that James coined for the search for objective knowledge about baseball – “saber” from SABR, the Society for American Baseball Research".

In other words, where a journalist would start with “Derek Jeter should be in the Hall of Fame”, James would start with “Should Derek Jeter be in the Hall of Fame?”, and not in the lazy-local-news-headline way where you know from the question where the answer is. More likely, James would start with “What kind of player is in the Hall of Fame? Does Derek Jeter meet that standard?”

I suspect that this distinction is obvious to most of you reading this (though it’s easy to find places in our public discourse where nobody seems to understand it.) But it was a big deal to 12-year-old me.

Later, I remember an epic dismantling of the phrase “Pitching is 75% of Baseball”, starting with wondering what that even meant, and then going one by one through the things that would be implied of that statement was true, determining that none of them actually were, and eventually concluding that even the baseball traditionalists who were fondest of the claim didn’t act in any way consistent with actually believing it. I can still quote large chunks of that one.

Some quotes didn’t really become meaningful to me until I started writing myself:

“One of the operating assumptions of this book is that you either own McMillan’s Baseball Encyclopedia or don’t care what it has to say. In either case, you don’t need me to tell you what an outfielder’s assist totals are”

I’ve used some variant of that comment for every book I’ve written (though it didn’t always make into the final version). I’ve also used in when reviewing books. It’s a really useful way to think about your audience, to realize that you can assume knowledge of or disinterest in certain information.

Another quote that was big with me when I used to read academic papers all the time, but that I also keep in mind when I write.

“This isn’t a bull session, this is science. I only write like it’s a bull session because I don’t like how scientists write”

James is always been a little cranky on the subjects of professionalism and expertise, which he sees as often being used as nothing barriers to keep out the riff-raff.

“When you write something it is either true or false and being an expert or not being an expert has nothing to do with it”

What’s really stuck with me, though is the way James went about seeking more objective knowledge. The process was simple.

  • Ask a question.
  • Determine something that is observable that would be true if the answer to the question is true.
  • Use small, empirical measurements. James is the king of quick-and-dirty measurements that favor ease of calculation and understanding over multi-digit precision.
  • Compare similar items that differ in one aspect. In the mid 80-s James was more excited about a method to measure how similar two players were than almost anything else, because it allowed him to create controlled studies.
  • Follow the data. You probably won’t learn what you expect. Respect the data and respect its limitations.

If you are interested in James’ baseball work, the best introduction right now is probably the Historical Baseball Abstract, which is an overview of both his statistical methods and his historical interests. A more biographical look at his effects can be found in Moneyball, by Michael Lewis, which is about how the Oakland A’s applied James-style methods to actually win games. It’s a great non-fiction narrative, and Lewis is, as far as I can tell, unusually factually accurate.

James’ most recent book is Popular Crime, which is not about baseball, but rather a historical overview of crime stories that become pop-culture touchstones, and also the books that have been written about them. It’s cranky, scattershot, obsessive, and hard to put down.

Red Buttons, The Uncanny Valley, And BDD Workshops

I want to tell you about LoneStar RubyConf and how my session went and all that, but first I want to tell you this seemingly unrelated story.

Once upon a time, my Senior undergraduate project was an educational software tool I built to teach fractions to elementary school students. (To give you the time frame here, it was written in Visual Basic 1 on Windows 3, and I had to ship my own desktop to the school to ensure that they’d have something I could run it on. Also, I travelled to the school via dinosaur.) Anyway, the metaphor for the program was slices of pizza, and at the beginning of the game, the student saw an uncut pizza on the screen. Times being what they were, I was using the VB graph library to draw the “pizzas”, so a new pizza was represented by a red 3D pie chart, which means it basically looked like a red cylinder.

The first student sits down and starts clicking on the pizza like there’s no tomorrow. I immediately realize that the red cylinder that I had set up to be a pizza looked like a huge red button right in the middle of the screen. I couldn’t possibly have given it more focus – honestly, it looked like it might launch missiles or something. And I know, that even though I had never thought of it in that way, that every student is going to do the same thing and that I’m going to spend my day telling people not to click on the pizza. Which is what happened. And I felt like an idiot – how could I not have seen it before?

Which brings us to my workshop at LSRC, “Correctness is only a side effect: Improving your life with BDD”. Here was the plan:

  • I wanted the workshop to have kind of a code retreat kind of flavor, where the attendees would be able to focus on the pure process without regard for real-world constraints.

  • The idea was that there would be a hands-on code problem, some discussion of how that was done via BDD based on the student’s concerns, then some prepared material based on the topic.

  • The extended example was some kind of restaurant recommendation system, where each restaurant would have a score based on, at first, just ratings, then cuisine, price, location, and so on. The plan was to build up an increasingly complicated score function than show the process of using BDD to refactor it to it’s own scoring engine.

Well, that didn’t work out. Some of it did. The prepared material was decent – I’ve used a lot of it before. A couple of other things happened, of which the most interesting was how the attendees interacted with the problem.

I started by presenting the problem and mentioning that we were going to be focusing on testing a score method, because that was where the interesting logic to test was going to be. We walked through the failing test for initial conditions, did the method returning a literal to make the test pass, forcing a dynamic method with another failing test. So far, it seems to be going smoothly from my point of view. This was quite an advanced group of students – often when I do these workshops at regional conferences, the attendees are on the newer side, but this group was experienced, knowledgable, and already largely bought into the idea of BDD. (Based on earlier experiences, I had pitched the material maybe a little to beginnery for the crowd, causing me to worry if I was presenting any useful information to them at all).

Soon it’s time to break out for the first hands-on example, which is adding some new features to the score function. And the conversation went something like this: (I’m compressing this a bit for dramatic effect…)

Me: And the task is to make recommendations based on cuisine and price. You can do this by filtering a list of restaurants, or, I’d recommend trying to do it by modifying the score function.

Clever Attendee: How do we store the list of restaurants?

Me: Oh. Um. I don’t really care. In a real system the framework would manage that. You can explicitly pass an array of restaurants if you want, or just test the score function for a single restaurant.

Clever Attendee: Okay. But how should I store the list of restaurants?

Which was my red button moment. Of course somebody coming to this problem for the first time would want to know how things were stored. Of course a person who didn’t know what I had planned for the rest of the day would worry about that.

And I realized that I had landed in the uncanny valley of example problems – close enough to realistic for people to care about practical concerns, but not specified enough for those concerns to be nicely handled. And I missed it because I was fixated on how I would test the score method.

We worked through it, though, and even did another round of examples using mock objects to fake out a location service. Still, we weren’t able to get anywhere near my plan of building up a complex system via BDD. Again – my fault for not getting the example right – the attendees were all great.

Ironically, I think I could have gotten away with it if the example was in print, where I would been able to just work through the changes in the score example.

Toward the end of the day, I kind of got the feeling that everybody, including me, was a little frustrated, so I just came out and said it. “I think the prepared material has been fine, but I don’t think the example has really worked. Would anybody mind trying a more abstract, code kata-like problem via BDD as the last example.” Everybody pretty much unanimously picked the abstract example, and so we pivoted to the abstract problem that I wrote for Ruby Learning a little bit ago. People seemed to work on that enthusiastically.

In the end, I think I provided value for everybody that was there, many attendees said nice things. But I’m annoyed with myself that I wasn’t able to deliver everything I wanted to.

Lessons for next time:

  • For this workshop, it seems likely that a well-specified but abstract problem is going to be better than a less-specified but nominally real-world problem. I think if I did this next time, we’d build up a simple game.
  • The content of any workshop like this is always dependent on the attendees needs. As the presenter, I have to be paying attention to how people seem to be doing. As the attendee, you should feel free to let the presenter know what you are hoping to get out of the session and if it’s working for you.

So, thanks to those of you that came out – you were great, I hope you learned something, and I appreciate they way you helped me improve my teaching skills. But I really hope you learned useful stuff, too.