Grocer has gone unmaintained for most of 2014, and it was obvious how to recover from a problem we were having with it where Apple would close the persistent connection we were using to send notifications, and so any notification sent after that would be lost. So I used Josh Symonds’ technique (with some tweaks I’ll mention later) to send them in a more robust way.

The one thing that Grocer does out of the box that Houston didn’t that we really needed was a way to send Passbook Push Notifications. These just like regular Push Notifications, however they are totally blank, sent to a token the pass registers with your server, and only work against the **Production **push notification gateway, using a different SSL certificate than your standard cert. This causes some problems because Houston assumes the Rails development environment should send pushes against the dev apple gateway.

So, what this means in reality is that you need 2 pools of persistent connections to apple’s gateway, and you need to override the gateway that Houston defaults to to be the production one only for the passbook updates.

Here’s the gist of the code I used:

class APNConnection
  def initialize(pem, uri)
    @uri = uri
    @certificate = File.read(pem)
    setup
  end

  def setup
    @connection = Houston::Connection.new(@uri, @certificate, nil)
    @connection.open
  end

  def write(data)
    begin
      raise "Connection is closed" unless @connection.open?
      @connection.write(data)
    rescue Exception => e
      attempts ||= 0
      attempts += 1

      if attempts < 5
        setup
        retry
      else
        raise e
      end
    end
  end

  def method_missing(m, *args, &block)
    @connection.send(m, *args)
  end
end

Then, in an initializer, I set it up like this:

$APN_POOL = ConnectionPool.new(:size => 2, :timeout => 300) do
    uri = Rails.env.production?? Houston::APPLE_PRODUCTION_GATEWAY_URI : Houston::APPLE_DEVELOPMENT_GATEWAY_URI
 APNConnection.new(GOLDSTAR_PEM_PATH, uri)
end

$PASSBOOK_POOL = ConnectionPool.new(:size => 2, :timeout => 300) do
    APNConnection.new(GOLDSTAR_PASSBOOK_PEM_PATH, Houston::APPLE_PRODUCTION_GATEWAY_URI)
end

Now we have two pools and the passbook push notifications are only using the production gateway. Notice we’re using two different PEM files. The PASSBOOK_PEM file I’m using is taken from the “Pass Type IDs” section of the Apple developer site. Download and convert to PEM just like you would a regular push notification certificate. It’s also the same certificate you’re signing your passes with.

Finally, we need to construct a notification.

notification = Houston::Notification.new(device: registration.push_token)
$PASSBOOK_POOL.with do |conn|
    conn.write notification.message
end

The important part of this code is that the “device” we’re sending this to is not actually a device token, like a regular push notification, but instead the pushToken that comes over when a passbook pass registers with your web service.

And that’s it.You should now be able to send both push notifications and passbook push notifications in the same app.

I’d like to think that we could look at some other professions and see how they define it. Doctors have the saying “do no harm”, pretty good. Architects, I’d guess, have to be able to design a building that doesn’t implode. Plumbers have to build a system of pipes that doesn’t get backed up and doesn’t leak. Lawyers, at the most basic level, just need to know the laws. They just need to be correct.

If you try to fix your sink, and it starts spraying water all over your kitchen, you might proclaim “I’m no plumber!”. If you gave medical advice to someone, and they got sick, you’d say “I’m no doctor!”. Almost all statements prefaced with IANAL are wrong, because that person doesn’t actually know what the laws say.

I think we could sum this up by saying, the basis of most professions is the ability to not break anything, or be incorrect in what you say.

So, what can we say about programming? How do you define what makes someone a professional? Correctness? All software that I’ve ever used has been incorrect in one way or another, so we’re going to have to throw that one out. Let’s get even more basic.

The minimum attribute of being a profession programmer is that you deliver working programs. Your code works. It does not break. It does not make things worse.

How many programmers do you know that can say that?

I’m going to pick on Avdi’s post just a little, but this is more-so criticism of every LoD explanation I’ve ever read. I think all of these explanations of LoD are actually quite contrite and not addressing the real problem. Avdi (and others) seem to focus on “Structrual Coupling” or exposing the “internal” (actually external*) structure of your objects to other objects that don’t need to know it.

An Example:

def user_info(user) 
    "Name: #{user.name}. Boss: #{user.department.try(:head).try(:name)}"
end

Avdi does a beautiful job illustrating why this code is a problem but I want to go a little deeper.

The more insidious LoD violation see in codebases is what I’d call “behavioral” LoD violations, or, when the behavior of a class relies on the behavior of objects that are distant in the object graph.

My example needs a little setup. Lets say you have Vehicles which has_many Platforms which has_many Models which has_many Versions (and Platforms has many Version through models). Pretty simple 4 level deep object graph that a car manufacturer might have. A very common set of objects you might want is to know which Platforms are actually in production. Some our outdated, some are future, but you want all the platforms that are currently in production.

Now, I know how I’d do this, but I commonly see code like this:

class Vehicles
  def current_platforms(options = {})
    platforms = platforms.find(:all,
                        :conditions => 
                          ["platforms.on_date >= ? AND platforms.status IN ('open', 'cancelled') AND platforms.cached_inventory_status != ?",
                            Date.today.to_s(:db), 
                            Platform.cached_inventory_status(:no_inventory)],
                        :order => 'on_date asc, time_note asc',
                        :include => {:models => :versions})
  
    if options[:skip_some_special_case]
      platforms.select { |platform| platform.versions.any? { |offer| !version.special_case} }
    elsif options[:skip_some_other_case]
      platforms.select { |platform| platform.versions.any?(&:other_case?) }
    else
      platforms
    end
  end
end

This code is a great example of my problem with how most folks end up simplifying LoD violations. No where are we chaining methods “too deep” or as it gets simplified to are we “using too many periods”. We’ve only used 1 period (because of a has_many :through =>). However, in our if statements, we are tightly coupling our code to the behavior of a class that is 3 siblings away from the one we’re working in. Nasty. Never should a Platform do operations on, or even know about, a Version.

So why is my example actually worse than something.try(:something_else).try(:a_third)? Well, lets get back to that * I left on “(actually external [structure])”.

Most people seem to classify the active_record generated attribute accessors of Rails model classes as “internal structure” (Avdi doesn’t, I should state for correctness). These are most certainly external structure. You can override them and return whatever you’d like and attributes[:foo] is actually the “internal” accessor for all active_record classes. External structure, in every project I’ve ever worked in, has been the most consistent, least volatile part of the codebases. External structure almost never changes, and when it does, it’s typically very easy to change (it’s not even a refactoring, it’s just changing the messages exchanged between classes).

My example relies on behavior of a class 3 classes away. If there’s anything I’ve learned, it’s that behavior is always more volatile than structure, and as Avdi points out, LoD really starts hurting as code churns and whatever your LoD relies on changes and becomes more and more complex.

So the big question is, how do we fix this?

It’s actually a theoretically simple fix, and similar to the fixes in Avdi’s post: delegate the behavior down the object graph!

class Vehicle
  def current_platforms(options={})
    if options[:skip_some_special_case]
      platforms.reject(&:special_case?)
    elsif options[:skip_some_other_case]
      platforms.select(&:other_case?)
    else
      platforms.select(&:regular_case)
    end
  end
end

class Platform
  def regular_case
    ...
  end
  def special_case?
    models.special_case?
  end
  def other_case?
    models.other_case?
  end
end

class Model
  def special_case?
    versions.special_case?
  end
  def other_case?
    versions.other_case?
  end
end

class Version
  def special_case?
    ...
  end
  def other_case?
    ...
  end
end

Now, Platform knows nothing about versions, versions can easily change what defines the “cases” without any changes to Platform and ironically, when I made this refactoring to the original source I got this derived example from, it’s actually more efficient. Removing the explicit find that started the original method means that if we’ve already loaded this object graph, even outside of this method, we can keep reusing it without going to the database.

I hope this helps, and for the love of Demeter, can we stop describing it as “using too many periods”?

I use the term “turd” often when talking about products, either hardware or software but I’m not always sure people know what I mean.

A turd is something your company “has to do”. Sometimes they sink and sometimes they float, but they are always mandatory.

A turd can be polished and it can be of any shape or size, but at it’s core, it’s still excrement.

Turds always come from somewhere. Sometimes, usually the ones that float, turds come from good things. The right things. Things like user needs, innovation, obvious holes in the market demanding to be filled.  Many times, however, turds come from bad places, these are usually the ones that sink (and stink). Stinky turds come from fear, they come from reactions to competitors, they come from “obligations”.

Everyone makes turds. The iPod Touch is a floating turd. Apple was obligated to make it. How could they resist? They’ve sold a ton because of the branding and the apps and the advertising, so it’s a shiny turd, but a turd no less.

Most (all?) of the iPad “killers” are turds. They are reactionary. They aren’t innovations, they are year late catchups powered by software that went from being something new to a turd the day the App Store launched.

The Facebook platform was, in it’s inception, pretty awesome. It’s turned in to a turd through, what I can only imagine has been, some epic bikeshedding,  beauracracy and abuse. I bet Zuck would kill it if he could, but instead he’s “obligated” to keep it going.

I don’t even think turds are bad. Turds can be great. They can be just what a company needs. But lets call a spade, a spade, or a turd.

One of the hardest things about designing web applications is presenting the multitude of types of information that is necessary at any one time. What do you display? What do you leave out? What information is more or less important than other information? If a piece of information is actionable, how do you visually inform the user of that?

Recently Twitter redesigned their interface using a new 2 panel layout where the sidebar dynamically changes, allowing for deeper inspection into the tweets that show up in your timeline. From a design standpoint there are a number of things that are great about this. The proportions (using the golden ratio) are excellent. The metaphor of a slide out panel is excellent. The exprience over “old Twitter” for reading conversation is vastly better.

However, there are 2 things that specifically bug me about the new design:  what I’d call the over stylization of the content and an over abundance of information.

This is a conversation in the side panel between two people I know. The first problem is that I think this is too much information. Here is what I see here: close link with icon, 3 tweets in two distinct styles with avatars, usernames, real names, timestamps, API client names and conversation links that link to the same conversation I’m viewing. There is also a user profile, which is in the same style as a tweet except the user’s bio is in italics. There is also links to use the original tweet in all the functions Twitter provides and the panel even goes on to list out other tweets from @bleything, however I have chosen to crop those out. Keeping in mind that my original intention was to view a conversation, and I came upon that conversation by clicking on a link in a original tweet, my goals are fulfilled but I’m also bombarded with more extraneous information than the original conversation contained.

Second, although there are probably less than 1000 characters here, and less than 420 characters of the information I requested when I wanted to view the conversation, there are no less than 12 distinct combinations of font weight, color and size.

Lets compare this with a “conversation view” from the Echofon Mac desktop app.

I find Echofon’s conversation much easier to read, and if I want more information, such as the API Client used to post the tweet or the user’s bio, I don’t mind digging deeper through the pathways I already know exist in the app. If I like to do something with one of the tweets, hidden controls appear when I mouse over. And even though there are graphics, the UI here is cleaner and only contains 2 text styles.  Literally every piece of information or action provided in the new Twitter conversation is accessible via either 1 mouse click or hover.

Designing applications is always about more than what the app look like. It’s how the app works, what information it presents, and making sure the user can easily and clearly achieve their goals.

A Rails view anti-pattern is that they very quickly turn into a nasty tangle of conditional html blocks.

Example:

<code class="ruby">
<% if logged_in? && @user == current_user %>

Simple example, but what is the intention of that code? Why are you really checking for? Give that state a name.

Change that to:

<code class="ruby">
def viewing_own_profile(user)
  logged_in? && user == current_user
end

<% if viewing_own_profile(@user) %>

Now you can test that helper method without resorting to rendering a view and parsing it to check if elements exist, the state you care about is named and the intention is clear.

“Ohhhh! It’s the hipster speaker!” – @didip

That’s what my co-worker said when he walked into the office this morning. Waiting for me when I got to work was the new Jambox by Jawbone. You may remember the video for the Jambox that went around the interwebs that featured a hipster looking dude and set the tone that these speakers that could replace your stereo as well as your conference phone in your office. Well guess what? I tend to be on daily of conference calls (via IAX via Zoiper) and we really needed a stereo for our PDX Studio, so a pre-order was made and the Jambox was delivered!

[st flickr=http://api.flickr.com/services/feeds/photoset.gne?set=72157625397638016&nsid=71881727@N00&lang=en-us]

More photos of the Jambox on my flickr.

The first thing you’ll notice is that it comes in a shoe box (hipster) with a screen printed boombox on the top. I will admit, the design and packaging is very apple, but urban hipster instead of the modernist-chic of Jonathan Ivey, and it’s pretty sexy. Upon taking the top off, I took out the Jambox and put it on the desk and tried to turn it on, nada. This thing doesn’t seem to come with a charge. So I hooked it up and pushed the top button, again, nothing. Finally I noticed there’s a sliding switch on the side, slid that on, and it announced it was ready to pair. The Jambox seems to have a few status messages that are spoken aloud to you. I like this.

I also love the size and weight. The Jambox is TINY! It’s smaller than a chipotle burrito. It’s lighter too!

It was pretty easy to get the Jambox to initially pair with my Macbook Pro (10.6.5 fwiw). I fired up iTunes and played some toons and it sounded terrible! I was a little bummed, but I soldiered on. My co-worker and I started trying to connect other devices, my iPhone, my MBP but using Zoiper to make a call, and in this process we figured out that we had the Jambox sitting on it’s side! Looking back, I can see how they intend for you to use it, but my co-worker and I are pretty smart guys (heck, he’s even got a CS degree!) and we had literally no idea which end was up. Here’s the good news, when you do get the Jambox right side up, it sounds awesome.

Let me tell you a little about our office. It’s got 16 foot ceilings, it’s about 12 x 12 and it’s one of the more echo-y places I’ve ever been. Using my trusty Harmon Kardon iSticks, audio sounds pretty terrible in this office. However the Jambox actually lives up to it’s marketing. For a tiny (this thing is just slightly longer than a sharpie), wireless, and battery powered speaker it sounds great! It’s got so much bass, it makes my desk vibrate and will even dance across the table. And surprisingly enough, it’s actually less echo-y in our little studio than the multi-hundered dollar, USB speaker system.

As a speaker phone, I haven’t used it for any long meetings yet, but initial tests are great. In our cave, using the built in input and output of a MacBook Pro results in terrible echo and looping even in Apple’s iChat (which does noise canceling). The Jambox exhibited none of this behavior. I’ll tweet more about this when I use it tomorrow on a few hour-long calls. Certainly, the on-board echo canceling Jawbone is known for is very nice on this unit.

However, it’s not all unicorns and rainbows: Bluetooth audio still kinda sucks. I spent a fair amount of time trying to reboot the Jambox, trying to get the computer to forget it so that the iPhone would notice it (when it did, it worked/sounded awesome), and quite a bit of time trying to make the MBP recognize the Jambox as an audio input/output device. This was not easy and led to much frustration which turned in to, at the end of the day, somehow having the bluetooth in my MBP completely turn off necessitating a reboot of the computer to get bluetooth to turn back on again (annoying when you’re also using a bt mouse). By far, the biggest letdown of an otherwise satisfying user experience, is that using it wirelessly, with multiple devices, totally sucks. The other weird thing is that the Jambox shows up as 2 types of outputs, one a “headset” and one a “speaker”. I don’t know when to use which, or what the ramifications are of doing either. Also, I had the absolute **worst **luck trying to get the Jambox to work with Zoiper. I think the final combination was, turn on the Jambox, pair with the macbook pro, choose it as an input/output, and finally start up Zoiper (with the Jambox already programmed as the input/output in the preferences). How this will work when I use Zoiper with headphones later on, we’ll see.

Overall, is it worth $200? I’d say the jury is still out. I find it hard to recommend it at this point, because the bluetooth stuff seems like completely voodoo to get working, but maybe after I better figure out pairing with different devices I’ll change my mind. For the price, you can buy some seriously good speakers, and its hard to tell how Apple’s Airplay technology is going to shake out on the speaker-system front (numerous manufacturers have announced support, but I haven’t seen any products hit the market). I certainly would find wifi based speakers more appealing, but I doubt we’ll see Airplay speakers that can also work as a noise canceling speaker phone for a small office/conference room.

This is the easiest, fastest and best-to-develop-in way to get a rails dev stack up and running on OS X 10.6 (Snow Leopard).

I actually find that it’s pretty easy, if everything is done in the right order.

1. Install XCode
2. Install Homebrew $ ruby -e "$(curl -fsSL https://gist.github.com/raw/323731/install_homebrew.rb)"
3. Install git using homebrew $ brew install git
4. Install mysql using homebrew $ brew install mysql
5. Install rvm (and follow the instructions to set up bash and don’t forget to open a new terminal window) $ bash < <( curl http://rvm.beginrescueend.com/releases/rvm-install-head )
6. Install Ruby Enterprise Edition $ rvm install ree
7. Make REE the default Ruby $ rvm use ree --default
8. Tell rubygems to not install rdocs
   Put the following lines in ~/.gemrc install: --no-rdoc --no-ri update: --no-rdoc --no-ri
9. Install Passenger $ gem install passenger

Now follow that up by running the install script (and follow the directions)

$ ./passenger-install-apache2-module

At the end of the install process it will give you instructions to add 3 lines to the “Apache configuration file”, but it won’t tell you where your apache config file is. It’s at /etc/apache2/httpd.conf
10. Restart Apache
At this point, if you’re using 10.6.5, you might do a sudo /etc/apachectl restart and run into the following error:
/usr/sbin/apachectl: line 82: ulimit: open files: cannot modify limit: Invalid argumentTo fix this, edit /usr/sbin/apachectl and change ULIMIT_MAX_FILES to an empty string.Now you can restart apache.
11. Install PassengerPane 1.3 www.fngtps.com/files/2/2009/09/PassengerPane-1.3.tgz

BOOM! Done.

Well, for me, I had to gem install isolate and Rubymine and then I was done, but you get the idea. Just load up the Passenger Preference Pane, point at site at a rails project on your hard drive, and load it up in your browser. Assuming your rails app will boot, you should be good to go!

I presented at Dev Nation Portland last weekend. These are my slides:

The question seems pretty obvious, “Who should be writing the acceptance tests for your software?” I think most people will first answer with “Programmers!”. There might be a few “testers”‘ maybe even a “the customer and programer pair”. These are all fine answers. Unfortunately, I’m starting to think they are wrong.

You are doing BDD right? So you already care about the “b” word: behavior. You care enough to differentiate yourself from the lowly TDD-ers. I’ve got news for you, there is a whole group of folks that care even more about behavior than you do. These people are called Interaction Designers and you probably don’t have one on your team. Don’t get me wrong, everyone that has ever written software has done interaction design, you probably weren’t conscious of it, or if you were, you probably did it poorly (unless you’re an interaction designer, and then you probably don’t read my blog).

Just who is doing IDx in your organization is easy to figure out. When you write a spec, you know, those “it should. . . “, “When” and “Then” statements, who fills in the blank? I’d guess it’s usually the developer (that’s been the case every where I have worked). Sometimes you might ask the customer, product designer, product owner, project manager, designer, or someone else on your team. However, this is where I think we’re doing it wrong. I’m starting to get the feeling that the person that should be filling in these blanks should be the interaction designer (ID). IDs are the people that know your users, they know what your users want, what they need, and what their end goal is. They know where your users sit when they use your app. They know what time of day they use it, they know if they are bored or tired or in a hurry. And most of all, they know what “it should” do and they are right. Do you know this stuff? Do you care? I’ve worked with programmers that were offended to even be in meetings where we talked about personas and end users!

I was recently involved in a little experiment we called “Agile Up To Here” which was (among other things) a 1 week agile bootcamp for Alan Cooper. You might recognize that name if you have ever heard of interaction design because Alan invented the term. He’s written a couple books on the subject, The Inmates Are Running the Asylum and About Face 3: The Essentials of Interaction Design. Anyway, after looking back at the week, I was trying to figure out what we could have done better. We were really agile. We could deploy from day 1, we had CI, we tested the shit out of everything, we paired all the time, we had the customer (Alan) in the room and on the team, it was sweet. But there was still something wrong.

Duh. We had an interaction designer in the room but he wasn’t thinking about IDx, he was learning agile. So who decided what went after “it should” in our app? Programmers, the worse-case choice. And what happened? On Friday, our last day, one of Alan’s IDs paired with Elizabeth Hendrickson and they finally started doing some real interaction design. But it was already too late, the damage was done. We had Interaction Design Debt™.

But why do you need IDx? The job of an ID is to figure out what a user wants to accomplish and the to ensure the application does precisely that. Anything your app does that doesn’t go to this need is waste, and any compromises are mistakes. Programmers, and I say this as someone who has almost solely as a programmer for the last 3-4 years, should be focused solely on figuring out the simplest code that could possibly work and implementing just that. The person that figures out “what could possibly work”, however, should be the ID. This must be a tight loop, and it must take place day in and day out.

Programmers are typically terrible at weighing the needs of the user against all the other things they have to keep in mind. If you don’t believe me, you’re either delusional or a programmer. Which is precisely the problem. This is something most people don’t know they don’t know. Or they don’t know they are actually pretty bad at it. Visual designers can also be pretty bad at IDx. If your designer just hands over Photoshop files with no instructions of how things should behave, thats probably because they are a bad interaction designer.

“Business people” are also usually bad at it, but for almost the opposite reason. Typically I’ve noticed that business people (which usually includes marketing folks) fall into 2 categories. Either they are too solution focused “let’s do it like so and so” without thinking if that’s actually the way it should be done for their users, or they don’t actually care about the implementation. The first group are doing IDx poorly and the second group doesn’t want to write specs. They don’t want to work at the level of thinking required for IDx and programming. They have a business goal. Let’s say it’s that they “want users to be able to sign up for a newsletter”. That’s the level they want to work at. The way the “user does the sign up”, “What happens when they click the “sign up” button?”, “What is written on the button?”, “Does the user have to confirm their sign up?”, and all the 100’s of questions that go along with this feature isn’t the level that most business people want to be involved. And when that is the case, why would  you want them to be involved in writing ATDD tests? If the answer is “because they are the ones that can answer that question” then you’re falling into the same trap that me and a lot of programmers have fallen into, because that just isn’t true. You’re actually looking for an interaction designer, not a business person.

Now that I’ve, I hope, changed your mind about just who should be writing these “tests”, let me get into the part that I’m not quite so confident about. Maybe what I’m talking about shouldn’t actually be expressed as “acceptance tests”. I mean, what happens and what a users sees when they sign up for a newsletter may not really be “business rules” or “business logic”, but isn’t it just as or more important? It’s important enough to me that I’d like to test it and make sure that what I think my code is doing is actually doing what I think it should. In fact, in most of my experience, these types of things are usually much more important and a much larger part of the application than the “business logic”. If you look at something like Facebook, where is there any business logic in that application (is there even any business, I don’t know)? I guess there could be some  in the privacy/permissions area. However, wouldn’t you want to test the multitude of things that happens when someone “likes” something? An interaction designer should be specifying what happens and a developer needs a way to be sure that their code does just that. What do we call those tests? How should we be doing that testing?

[Paraphrasing] There are lots of things we don’t know that we don’t know about [the project we were working on]. Agile is how we optimize our process for learning those things. – Ward Cunningham

One of the things that really changed how I thought about building software was learning about the Dunning-Kruger Effect. I didn’t know that’s what I was called, mind you, but I certainly had witnessed it and once it was explained, it made perfect sense. What is the Dunning-Kruger effect?

“people reach erroneous conclusions and make unfortunate choices but their incompetence robs them of the metacognitive ability to realize it.”  – http://en.wikipedia.org/wiki/Dunning-kruger_effect

What does that have to do with Agile? Well, some of the seeds for Agile, at least from Kent Beck and Ward Cunningham’s influence came from the days when those two guys shared a lab and were partners in R&D at Tektronix. I’ve written about this before, but basically, their job was to come up with, every set period of time, some idea that Tektronix should pay a team of guys to develop out into a product or tool. So, KB and WC would come into work every morning and one of them would propose an idea and they would spend the morning trying to hack the idea into working software. If it wasn’t working, they’d go back to working on whatever was the last best idea, and then at the end of the time period, they always had something that worked that they could turn over as an idea. This is where some of the seeds of TDD, iteration, and other ideas that are now staples of Agile came from.

But why would you do that? Why would you essentially start over every morning? Well, as it turns out, humans are really bad at knowing what they don’t know. So why not come up with an idea and just work on that idea until you had something? Let’s explore that. . .

BDUF is for those that don’t understand the Dunning-Kruger Effect

I don’t feel like this is a very controversial topic (that might also be the other end of the K-D Effect) because I think this one has already won out. It certainly has in the ruby community. I’ll go ahead an explain it though. BDUF stands for “Big Design Up Front” and most non-enterprisy, non-corporate software teams know, you can’t design all of your code before you write your code. And the agilists out there will even say that the only way to write truly simple clean code is to write a test first. I hope this isn’t a big shock to anyone. If we examine why this is true, we pretty quickly get to a point where you say “we don’t know enough about the code to design the code without first writing some code”. In other words, we don’t know what we don’t know about the code yet, we have to learn what we don’t know and adapt our application architecture as we learn. I guess if you get a CS degree, you’ll run up against a whole set of folks that don’t believe this, but I’ll go out on a limb and say that most of those folks also don’t write much software. Anyway, suffice to say, we’ve got a whole set of practices, red-green-refactor, continuous integration and deployment, to optimize against doing BDUF (among other things, surely).

Specification Documents are for those that don’t understand the Dunning-Kruger Effect

Another example (I think more important and less widely accepted, and the real reason I wrote this post) of the optimization for all the “things you don’t know that you don’t know” in Agile is that we don’t write spec docs. We don’t start out a project with a giant document that spells out everything we’re going to build. That’s not to say no one knows what we’re building, or has a vision of what it looks like when it’s done, au-con-trair, that’s definite a recipe for disaster (and, I think, most people’s biggest fear that haven’t participated in an Agile project). We spend the time to write all of this down in whatever format we would need to give it to a developer and walk away. Why? Well it’s that damn Dunning-Kruger effect. You can’t actually write a good spec, and not only that, those that don’t know this are the ones that precisely think it’s possible. No matter how many lines of code you’ve written, or UI’s you’ve designed, or businesses you’ve started, you will never know enough about what you don’t know to write a document that will cover every edge case, angle, possibility, challenge and decision that has to be made to successfully create quality software.

I hear this lot when I tell people this: “But you can change your spec” or “Good specs allow for learning”. I’m sure you can and I’m sure they do. Change and learning is precisely what agile is all about and not just embracing change, but optimizing for it. You’re always going to change that spec. Every project I’ve ever been on, at one point or another, something was too hard or expensive to be worth it and we’ve always changed what we’re going to do. Most of the time, this something was a surprise. It wasn’t what we thought would be hard or even something we thought we needed to do! I’ll even go further to say that some of the more successful projects I’ve been on, not only did we optimize for learning things early, we optimized for being able to change things easily.

The problem with writing a spec and then changing it, however, is that usually this renders part of the spec useless, or worse yet, it renders useless some “real work” you have already done. There’s a million quips and anecdotes people use for this, “Fail fast. . .”,  “If you’re not embarrassed when you launch your project, you waited too long”, etc. The reason people say these things is precisely because they’ve experienced the Dunning-Kruger effect. They’ve written a spec or built software thinking they had their bases covered, that they knew things, but they didn’t end up knowing everything and not all of what they thought they knew ended up being true. And many of these people have come to the conclusion that if they would have done less planning, and got to implementing even faster, they would have learned important information that they didn’t know they didn’t know earlier and saved themselves work. XP is about optimizing for this in a technical setting, “The Lean Startup” is about optimizing for this in a marketing and product development setting.

Since the weather was so wonderful here in Portland today, my wife and I decided to make fajitas for dinner. Instead of your regular “grill some chicken, fry some veggies” fajitas, I decided to do a version I saw Alton Brown do on good eats.

The interesting thing here is that I’m cooking the meat (skirt steak) directly on the charcoal. No grill, no foil, no pan, just meat directly to red hot glowing chunk charcoal. This develops and intensely smokey flavor in the meat. You can see there are large areas of “burnt” meat, but it’s not actually burnt, it’s just caramelized and full of flavor. I’ve never had skirt steak so tasty, very caveman, in a good way.

When the steak was done (3 minutes per side, don’t even think about touching it while it cooks, and then let it rest 15 minutes), I put a cast iron skillet directly on to the coals and let it get smoking hot. I put the standard white onion and green/red pepper that I drizzled with a little olive oil and salt and pepper. The skillet was so hot the veggies instantly started to caramelize and you have to stir them almost constantly or you will get a little burning. Cooking the veggies takes less than 5 minutes (definately don’t over cook them) and the flavor is also amazing. If you ever wonder why veggies take so much better in good chinese food, it’s because they cook them super super hot like this. As a side note, if you want to make really great stir fry and don’t have a really nice gas wok stove, this is actually a good way to do it.

Enjoy with a Cascadian Black Ale and plenty of guacamole, preferably on your beautiful patio with your bride.

I’m taking a trip to Baltimore between June 7th and June 11th.

railsconf