Mundane Essays

Generate SQL from your migrations

2009-02-20T13:07:00.005-05:00

On one of the projects we're working on, we needed to occassionaly generate SQL from our migrations. Déjà vu, I thought. A few minutes of Googling later, I remembered why: Jay and I had been on a project a couple of years ago whence we had the same need. Jay's code didn't quite work any more due to some ActiveRecord changes, and a search for an alternative implementation turned up nothing.

I took his code and modified it to our needs. A short time later, I had the code pulled out into a rails plugin, migration_sql_generator. Install it (script/plugin install git://github.com/muness/migration_sql_generator.git) and then run the rake task:

rake db:generate:migration_sql

Running this task generates two sql files per migration in db/migration_sql in the form 20090216224354_add_users.sql and 20090216224354_add_users_down.sql.

I've used the plugin with success using the sqlserver adapter, less luck with the mysql adapter (change_column and rename_column blow up because the mysql adapter checks for the presence of a column first) and no luck with the sqlite adapter. Haven't tried it with the postgres adapter.

Easily switch between Ruby 1.8.6 and 1.9.1

2009-02-20T12:05:00.011-05:00

NOTE: I don't keep Ruby Switcher updated anymore. Use RVM instead.

Chad mentioned that he'd gotten ruby 1.9.1 and 1.8.6 side by side on his workstation (his code for this is in his awesome spicy-config repo).

I took some time this morning to get a similar setup working. Now, on my prompt, I type, use_ruby_186 or use_ruby_191 to go back and forth between the Ruby 1.8.6 shipped with Leopard and a self-compiled install of ruby 1.9.1.

Steps for you to get there:

Compile and install ruby 1.9.1:


mkdir -p ~/tmp
cd ~/tmp
curl -O ftp://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.1-p0.tar.gz
tar xzf ruby-1.9.1-p0.tar.gz
cd ruby-1.9.1-p0
./configure --prefix=$HOME/.ruby_versions/ruby_191
make
make install

Install the ruby switcher:


curl -L http://github.com/relevance/etc/tree/master%2Fbash%2Fruby_switcher.sh?raw=true?raw=true > ~/ruby_switcher.sh
echo "source ~/ruby_switcher.sh" >> ~/.bash_profile

Note that I use ~/.gem for my gems. If you don't do that, you'll have to modify the switcher to specify your GEM_HOME. Type gem env and look for GEM PATHS to figure out what you should set it to.

Maatkit installation: the concise guide

2009-02-03T01:10:00.002-05:00

If you use MySQL, odds are you need Maatkit whether you know it or not. It's the Swiss army knife: I mostly use it to parallelize backup and restore of huge databases on multi-core machines, but it's also handy for fake splitting large files, executing sql on multiple tables and a whole lot more. (You also want mytop if you're wondering what's up with MySQL connections.)

Here's the install script if you too want Maatkit at your fingertips (and you do. trust me.):


#!/bin/sh
# tested on Leopard with MySQL installed using the package installer

sudo perl -MCPAN -e 'install DBI::Bundle'
sudo perl -MCPAN -e 'install DBD::mysql'
# you may need to force the install as follows:
# sudo perl -MCPAN -e 'force install DBD::mysql'

mkdir -p ~/tmp
cd ~/tmp
curl -O http://maatkit.googlecode.com/files/maatkit-2725.tar.gz
tar xzvf maatkit-2725.tar.gz
cd maatkit-2725
perl Makefile.PL
sudo make install

No network after copying an Ubuntu VMWare image

2009-01-22T09:24:00.003-05:00

After you copy an Ubuntu image, you'll probably lose your network connectivity. After a little bit of digging, it turns out that Ubuntu persists the MAC address of the network device in /etc/udev/rules.d/*net.rules . The fix:

  sudo rm /etc/udev/rules.d/*net.rules
  sudo shutdown -r now #to reboot

Git: things I love and manipulating remote branches

2008-11-14T09:44:00.008-05:00

I've been happily using Git for months now. The primary benefit for me has been the ability to work offline without messing with SVK, not having to use the svn commands for renames and moves, the ability to use multiple remote servers and better tools to look at branch level history (think gitk).

Branching is much improved, besides. In Subversion, to branch, you copy the current tree elsewhere and then you work in this branch and finally, merge your changes manually back into trunk (to wit, you have to keep track of what was already merged and not reapply those commits). In git, though, that's all handled for you. Another difference is best illustrated by example: you've started a new feature. Several file modifications later, you look at your diff and realize, "I should have started a new branch for this. doh." With Subversion, there's not much you can do automatically to get these changes into a branch. You'd typically now:

generate a diff
undo your changes
create a branch
switch to the branch
apply the diff
back to work

In git on the other hand, you type git branch feature_22.

Sweet, huh?

Well, not altogether. Pushing this local branch to a remote server is altogether too complicated:


git push origin feature_22:refs/heads/feature_22
git fetch origin
git config branch.feature_22.remote origin
git config branch.feature_22.merge refs/heads/feature_22
git checkout feature_22

Sure, you could have created the branch on the remote server first and saved yourself some hassle:


git push origin master:refs/heads/feature_22
git fetch origin
git branch --track feature_22 origin/feature_22
git checkout feature_22

Not exactly straight forward either. Neither are other standard branch related activities. Here's how you delete that remote branch:


git push origin :refs/heads/feature_22 # yeah, that's how you delete a remote branch.  :(
git branch -d feature_22 # delete it locally too

Fortunately, Git has a vibrant community that work to abstract away some of these complications. One of my favorite Git tools is git_remote_branch. By using it, working with remote git branches becomes a breeze:


grb publish feature_22 # publish a local branch
grb create feature_22 # create a remote branch and local branch to track it
grb delete feature_22 # delete the remote and local tracking branch

Ah, that's better!

Mingle, meet Git

2008-09-21T12:12:00.005-05:00

Several weeks back, Adam Monago, Mingle's product manager was visiting our office in Chapel Hill. One of the topics that came up was Git integration with Mingle. Alas, it sounded like it was a ways out. But he explained that the SCM integration was pluggable and that we could write the code and drop it in place, echoing things I'd heard from other ThoughtWorkers.

A couple of days later, Don and I were curious as to just what it'd take to implement the integration. Reverse engineering the interface we had to implement from the Subversion and Perforce plug-ins was anything but fun, but before the day was over, we had rudimentary integration working: we could see commit messages and the list of files modified per check-in. Since then, Don implemented the rest of it including Mingle-based source code browsing.

We've been using the mingle_git plugin for a little while with no problems. For performance reasons, we're not using the source code browsing from inside Mingle. Instead, we use GitHub's source browsing: see the README for instructions on wiring things that way too.

Installation is documented in the README. We've only used this on Mac OS, FreeBSD and Linux. Windows users, you may have luck by using msysgit.

Caveat emptor: if you browse around the code, you'll quickly conclude that it is a spike: we started with the subversion plugin and evolved it to this. Since the SCM integration API is not documented, we can't even be positive that we implemented it correctly (though the evidence suggests that we have). Also note that Mingle makes the assumption that check-in numbers are sequential, and that's an assumption that is not Git-friendly and it shows in the code.

Enjoy, but keep in mind that this is unsupported, use-at-your-own-risk software. For me, that's better than no Git integration. ;)

Note: Mingle's APIs changed from 2.0 to 2.1 and we haven't had a chance to update this plugin yet. If you installed this plugin, and are ready to upgrade to 2.1, you'll want to remove the plugin and then execute this SQL on your Mingle database: delete from plugin_schema_info where plugin_name = 'mingle_git';

Encrypt your client data in 53 minutes

2008-08-17T11:35:00.007-05:00

Thanks to Aaron's continued efforts to make us ever more security conscious, I've been encrypting client data on my laptop. This came up in conversation during erubycon (thanks EdgeCase for a fun conference with engaging evening events). A couple of people asked me to get them started on encrypting their data too.

Here are instructions. They're written for Mac users, but they'd be nearly identical for Linux and Windows users since TrueCrypt is available there too.

Install TrueCrypt.
Create a container based encrypted file. Pick FAT as the file system. I use both keyfiles and a password.
Erase the FAT partition and then format as HFS/ext2/[fs of choice] using Disk Utility/[partition manager of choice]. Name it client_data.
Mount the newly created partition.
Move your sensitive data to /Volumes/client_data. This is by far the slowest part of the process. While you wait, watch The Enemies of Reason (48 minutes -- everything else should take 5 minutes or less).
Modify TrueCrypt preferences to suit your needs. Some suggestions: leave encrypted volumes mounted when quitting TrueCrypt, set Auto-dismount volume after 30 minutes of inactivity in the partition.

As mentioned in my previous blog entry, I use a script to automatically create aliases to allow easy switching to project directories. All I had to do was switch that entry to point to /Volumes/client_data instead of the old ~/work/client_data. Now, when I want to work on client projects or contracts, I launch TrueCrypt, mount the container and open a new terminal window. All my old aliases work just like they used to.

Mac users: if you don't care about the cross-platform compatibility that TrueCrypt offers, and trust Apple to encrypt your data, you could use Disk Utility to create encrypted partitions instead. Some people insist it's more convenient (You know who you are!).

Lazy bash cd aliases

2008-06-29T13:04:00.011-05:00

Those of you who've found value in my last couple of bash specific posts may also like the latest addition to my ~/.bash_profile.

This one iterates through the one or more directories and creates aliases to the subdirectories so I don't have to. Here's the scenario: I've got a directory ~/work/ where I keep work projects, a ~/writings/ where I keep all the writing projects and so on. I used to have aliases to each subdirectory. e.g. alias project1="cd /Users/muness/work/project1". With shame, I admit that I maintained each of these manually. No more!

Install instructions:

curl -L http://github.com/relevance/etc/tree/master%2Fbash%2Fproject_aliases.sh?raw=true?raw=true > ~/.project_aliases.sh
echo "source ~/. project_aliases.sh" >> ~/.bash_profile

Usage instructions:

Move your work projects to ~/work.
Above the source ~/. project_aliases.sh add PROJECT_PARENT_DIRS[0]="$HOME/work".

You may be interested in my blog post over at PragMactic OS-Xer where I describe my motivation for these recent shell scripts.

bash: don't make me think

2008-06-16T19:56:00.008-05:00

Last week I figured out a way to make my life a little bit easier by abstracting the scm I was using and having the prompt indicate whether I was in a Subversion or Git. Thanks to Mike Hommey whose script I tweaked for my needs.

For a long time, I've wanted my iTerm tab title to be more useful. I started by having it display the last process I executed in that tab (this also shows the full path in iTerm's window title bar):


PS1='\[\e]2;\h::\]${PWD/$HOME/~}\[\a\]\[\e]1;\]$(history 1 | sed -e "s/^[ ]*[0-9]*[ ]*//g")\a\]\$ '

Next up I wanted to show the currently running command. Google showed me how:


trap 'echo -e "\e]1;$BASH_COMMAND\007\c"' DEBUG

Instead of trying to explain this code I'll quote the Bash man page:

BASH_COMMAND
The command currently being executed or about to be executed, unless the shell is executing a command as the result of a trap, in which case it is the command executing at the time of the trap.

Some more tweaks followed:

Distinguish between a previously executed command and a currently executing command by decorating them (I chose surrounding the former with braces and the latter with >/<. e.g. [ls] and >vi<).
Show the context of the executing command in the tab. This is just the repository where I executed the command.
Make this coexist with TextMate.

And a screenshot to summarize:

The code is in github/relevance/etc/tree/master/bash/bash_vcs.sh.

Install instructions:


curl -L http://github.com/relevance/etc/tree/master%2Fbash%2Fbash_vcs.sh?raw=true > ~/.bash_dont_think.sh
echo "source ~/.bash_dont_think.sh" >> ~/.bash_profile

Enjoy! Tested with iTerm on Leopard.

Stop the presses: bash said to embrace subversion and git

2008-06-10T19:41:00.009-05:00

Update: I've since updated and moved this script. See my new blog post.

I had a chance to pair with Rob today. On his console window, I noticed something I wanted: his bash prompt had an indication that he was in a Git repository along with the branch he was on. Later, after he'd left, I found myself wondering how that worked and that I simply had to have it, and I wasn't willing to wait a whole day to figure out how he'd done it. Patience is not a virtue. (In that spirit, click here for the code if you're too impatient to read the rest of this blog entry which I spent countless hours writing. Uphill both ways. In the snow.)

A few minutes of googling turned up a blog entry with relevant bash fu. The code there was for changing the prompt such that it indicated whether you were using svn, git, svk or Mercurial along with some repository metadata. A couple of minutes later (it took a while to copy and paste the code since it was interweaved with comments), I found out it didn't work on Leopard. readlink turned out to be the culprit. Instead of figuring out why it wasn't working, I replaced it with something simpler (specifically I used: base_dir=`cd $base_dir; pwd`). Voila, things worked: I now had a hella cool prompt that showed me if I was in a Subversion or a Git repository - I never used Mercurial, and left SVK for Git a couple of months ago. Yay.

Being who I am I had to do something more with this new ability to distinguish between Subversion and Git. And I knew exactly which itch to scratch: 90% of the time I use the same scm commands. I even had shell aliases for them so I wouldn't have to type them. A few minutes later I'd converted my previously Subversion specific aliases to generic ones that worked with Git too. Screenshot says it all:

If you want the same, download the script as ~/.bash_vcs and add source ~/.bash_vcs at the end of your ~/.bash_profile.

Buckets of mice

2008-04-25T10:23:00.012-05:00

We have 24" and 30" pairing stations, an intern, freshly roasted coffee delivered weekly, a fridge stocked with caffeine, more caffeine, beer, and Dave's Insanity sauce. We have cool t-shirts and all manner of radiators up on the walls, whiteboards and the Beta Brite. Music is served by our CI/Music server.

The bookshelves are stocked with reference materials, the occasional bottle of scotch, and recommended readings. On the list of recommended readings we've got The Carpet Makers, The Company, The Omnivore's Dilemma, The Eyre Affair, Behind Closed Doors, Bloodsucking Fiends and The Deadline, Men In Hats, Volume I, Don't Make me Think, The Insane are Running the Asylum.

Our favorite radiator is the Friday radiator. Fridays are special: we don't do billable work. Instead we open source, blog (self reference makes this blog entry extra cool), watch educational movies, play Wii on the projector. Here's today's:

Oh, let's not forget the buckets of mice.

This blog entry inspired by another excellent business card cartoon from Hugh Macleod.

cmd line history meme

2008-04-16T09:06:00.002-05:00

Rob tagged me. So:

muness$ history 1000 | awk '{a[$2]++}END{for(i in a){print a[i] " " i}}' | sort -rn | head
102 git
72 ls
63 cd
40 ss
35 rake
24 m
17 up
14 st
12 sc
11 ri

Tag, you're it.

Distributed Retrospectives

2008-04-11T12:10:00.012-05:00

Agile Retrospectives (Esther Derby, Diana Larsen) and Project Retrospectives (Norman L. Kerth) have been a great resource in facilitating - or helping others facilitate - retrospectives. I'll often leaf through them a day or two before a retrospective to remind myself of the framework (more on that in an forthcoming post), and to introduce new activities or create my own.

Something that neither of those books tackle directly is how to facilitate a distributed retrospective. Given that we've been running a few of those lately, I wanted to share some tips:

Your equipment matters. It took us a while to find a speaker phone that worked well for those in the office and those on the other end. It's hard enough to communicate effectively without being in the same room, without muffled voices. We use a Polycom unit with two extensions for a 20x16 room.
Prepare. There's a lot of preparation that goes into running a retrospective in person. You have to familiarize yourself with the project, look for a theme, send out invitations, pick activities (and backup activities in case one isn't working), and collect the tools/resources you need for those activities.
Google Docs is your friend. With its near real time updates for viewers and collaborators, it's been an indispensable tool to take notes. The facilitator or a scribe can update the document and others can see what's happening, on the fly.
It's not enough to use a Google Doc, you need to turn it into an online workspace that makes others feel like they're part of the process. For example, I prepare a google document with activities scheduled for the retrospective. I take care to:
- Clearly state activity names. When we move to the next one, it's enough to say its name and everyone can easily find the appropriate section.
- Describe the activity. Having a written description allows people who miss the spoken description to follow the intent as well as the process involved. Missing a description over a conference call can happen for all sorts of reasons, from people being more easily distracted, to phone problems.
- State the targeted time for the activity. People are even more restless on a conference call. This gives them a sense of the overall meeting's timeline.
- Copy or summarize information from previous retrospective documents for ease of reference.
Share with others. Sharing the document with others as collaborators (rather than just viewers) gives them the confidence that they can correct mistakes.
Don't forget to send an email shortly before the meeting that serves as a reminder, repeats the phone number/conference line details and includes a link to the Google Doc for that meeting.

I've shared a Google Doc template for a 2 hour iteration retrospective for 4 to 8 people you can refer to or use as a starting point for your own living retrospective document. Credit goes to Agile Retrospectives for the activities.

Testing declarative code

2008-04-11T09:20:00.007-05:00

For a while now, I've had my doubts about the usefulness of one aspect of test driven development (which applies equally well to behavior driven development): that it should be done 100% of the time.

The first time I came across this, was at ThoughtWorks. The question was whether we should TDD declarative delegations. I remember a several hour long conversation about the merits of tests for Forwardable based delegations.

class A
  extend Forwardable
  def initialize(b)
    @b = b
  end
  def_delegator :@b, :some_method  # Should I write a test before writing this declaration?!
end

A specification for this declaration would be:

describe "A" do
  it "delegates some_method to b" do
    a = A.new(stub(:some_method => :x))
    a.some_method.should == :x
    # or you could use the Handoff assertion:
    assert_handoff.from(A.new).to(:@b).for_method(:some_method)
  end
end

I didn't get the fuss -- it was clear to me that testing such delegations was wasteful and a maintenance hassle. But I didn't realize that this was part of a larger argument.

Not an isolated case

Since then, I've learned that to some developers this is a general rule. Here's another example, re testing stock ActiveRecord validation declarations, e.g.:

class Model < ActiveRecord::Base
  validates_presence_of :attr_1
end

The test for this would be:

describe "Model" do
  it "validates_presence_of :attr_1" do
    model = Model.new
    model.valid?
    model.errors.on(:attr_1).should == "must not be blank"
  end
  # or you might write a helper that reflects on validates_presence_of declarations
  test_model_validates_presence_of Model, :attr_1
end

It took me a while (too long) to get the general pattern: these discussions I kept finding myself in all had to do with testing declarations.

How did we get here?

Test driven development as best as I can tell is a - pragmatic - descendant of formal specifications:

"A formal specification is a mathematical description of software or hardware that may be used to develop an implementation. It describes what the system should do, not how the system should do it. Given such a specification, it is possible to use formal verification techniques to demonstrate that a candidate system design is correct with respect to the specification."

Writing formal specifications for the majority of the software isn't practical. Writing tests first provides us a simple, practical way to write executable specifications. True, they don't give us the ability to use "formal verification techniques" to prove anything about our code, but they do give us confidence that our code does what our tests say the code does (as much confidence as we have in our tests).

The rule

The rule regarding TDD is: If you can TDD it and it's destined to be production code, you should TDD it.

The problem I find with this rule is that it causes us to write tests like those above that duplicates the declarative code. At best case it goes like this:

  # We write this code first in the spec:
  test_model_validates_presence_of Model, :attr_1 
  # we run it and watch it fail...
  # and then we write this in the model class:
  validates_presence_of :attr_1 
  # rerun the test and watch it pass...

I find this wasteful: We first implement the test_declaration_is_called (in this case, test_model_validates_presence_of) for every declaration. After all that work (and not to mention code that we have to maintain) we end up with a test that tells us what the declaration itself does. But with less readability and intent. Indeed, declarative code is in fact formal specification.

Guidelines not rules

Writing tests first is a great guideline. I do it almost all the time. But I don't do it all the time. It makes me angry when I change declarative code only to have a test that looks exactly the same fail as well.

OK, tests for declarations don't really make me angry. But they do make me wonder if the developer who wrote the test really likes to answer the question, "are you sure that you're sure that you want to do what you just said you want to do?"

Where there's smoke signals...

2008-03-14T10:59:00.005-05:00

In a previous post, I briefly described how we were using cc_campfire_notifier to get build success/failure notifications in campfire. cc_campfire_notifier has lost momentum over the last couple of months. Since we actively rely on the notifier for several projects, we've now forked it as smoke_signals.

The first release offers the following improvements:

Each notification includes a link back to the CruiseControl.rb build (so you have one-click access to the full details for each build).
Recognizes apr_error errors as SVN errors (so you'll spend less time scratching your head over generic build failure messages).
Speaks once into the campfire room whenever an unexpected error occurs (as opposed to speaking once per line in the backtrace).

Check out the notifier's home page for installation instructions or head on over to GitHub to browse the code.

Release early, release often, business edition

2008-03-06T08:46:00.003-05:00

One of the things we preach as software developers is release early, release often. I think ESR is right in that our primary motivation for this is often related to quality:

In the bazaar view, on the other hand, you assume that bugs are generally shallow phenomena—or, at least, that they turn shallow pretty quickly when exposed to a thousand eager co-developers pounding on every single new release. Accordingly you release often in order to get more corrections, and as a beneficial side effect you have less to lose if an occasional botch gets out the door.

As I've done more project consulting and management, I've realized that the benefits extend well beyond the technical ones. But I've had a difficult time articulating the business benefits to incremental, frequent releases.

Last week, Ross posted an article that describes one of the primary business benefits to frequent, early releases, Minimising the Speculative Risk of IT Investments:

With each incremental delivery, and every increase in tangible value, the intangible or speculative value decreases. The reduction in speculative value at risk represents a reduction in the total value that can be depressed through delays in delivery. Thus, early delivery reduces the risk of speculative value not being realised. Simultaneously, it reduces the volatility of returns.

What other benefits do you find to the business from releasing early, releasing often?

CC.rb Campfire Notifier Released

2008-02-07T18:19:00.001-05:00

Note: I've forked this notifier to add features and fix some bugs at in Smoke Signals. At Relevance, we make heavy use of Campfire for our distributed projects. One room per project, and we expect everyone to "be in" the relevant room associated with the project they're working on at the time. We use it to communicate: to ask for a pair (we've tried Leopard's Remote Desktop Sharing, but have no settled mostly on emacs + screen), ask questions, request code reviews (we've taken to using the topic for posting ad hoc requests like that), and make announcements.

This virtual space has many disadvantages over being in the same room as I'd been used to on my previous couple of projects, but it did have a nice perk: SVN commit notifications were right there alongside our own discussions. The notices were more useful than I expected, a quick, clear indicator of our pace on a given day.

Naturally, I wanted our other major automated task to notify us of CCMenu is OK, but it's disconnected from our primary virtual space (Campfire, as discussed above). Being lazy, I didn't want to build it myself, so I first looked around for tools that suited my needs. Much to my chagrin, none did, so I took the one that was closest and added to it what I needed: specs. Then came the stuff that was missing: ssl support and support for one room per project. And last but not least, to help deal with configuration hassles and debugging, I added logging.

If you're using CruiseControl.rb and Campfire, give it a whirl. Instructions are in the README.

Pi

2008-02-05T16:53:00.000-05:00

Managers and rules

2008-01-20T18:46:00.001-05:00

Jerry Weinberg, if you don't know him, is the author of more than a dozen books on software development and memorable laws such as the Law of Twins. In Quality Software Management: Systems Thinking, published in '92, he described what we might today call an agile team. (He lists several levels of software team cultures, ranging from Oblivious to Congruent. Along that spectrum, an agile team would fall somewhere along Steering, Anticipating and Congruent.)

At AYE 2007, I had the pleasure of meeting Jerry in person. Something that I was not aware of was his remarkable skill at helping others. Instead of answering a request for advice directly, he'd delve into the details, applying something like the 5 Whys. Within minutes, he would hone in on a rule that the person had imposed on themselves that was at the root of the problem. After expressing the problematic rule, he'd help them relax the rule into guidelines. Several people who've spent more time with him have echoed my gut feel that they too found this ability to help others rare and invaluable.

His approach to helping individuals is based on Virginia Satir's work in family therapy on survival rule transformation. An excerpt from The New People Making:

After you have written down all the rules your family thinks exist and cleared up any misunderstanding about them, go on to the next phase. Try to discover which of your rules are still up to date and which are not. As fast as the world changes, it is easy to have out-of-date rules. Are you driving a modern car with Model T rules? Many families are doing just this. If you find that you are, can you bring your rules up to date and throw away the old ones? One characteristic of a nurturing family is the ability to keep its rules up to date.
Now ask yourself if your rules are helping or obstructing. What do you want them to accomplish? Good rules facilitate instead of limit.

Last weekend, while attending a Satir workshop I was struck by the applicability of Satir's ideas on rules to teams at work. There too, rules can be unstated, ambiguous or inapplicable sometimes hampering our ability to get things done, other times making everyone miserable.

(For a valuable discussion on rules suitable for software development teams, check out the section on Rules in chapter 21 of Software Teamwork:Taking Ownership for Success. To summarize, the rules should be focused on ensuring that a team has "the capabilities and resources to do the right things, rather than on stepwise procedures to be dogmatically followed".)

In big companies the problems are magnified as fully connected networks of people become prohibitively expensive. For example, it'd take each person over a day out of every week for 25 people to stay in meaningful weekly one-on-one contact. (Indeed, the few who take the time to build an extensive network can become stars capable of getting things done faster than their peers could.) Additionally, in a big organization, it's likely that a rule that works for one group will be applied to ones where it doesn't fit.

The role of a manager is to engender an enabling environment. But how? Virginia Satir's approach to rule transformation provides one way. One which fits in well with the management advice in many of the management books I am familiar with, including Behind Closed Doors, Peopleware and Slack.

Here's how I describe the process:

Identify implicit rules and restate the explicit ones.
Explore how they came about.
Express the rules explicitly.
Clear up ambiguities in the team's understanding of each rule.
Evaluate each rule's applicability.

Having done this, you might find that a rule is:

Helpful and reasonable. So, apply it!
Helpful but impossible or untenable. Then transform it into one or more guidelines that aren't prohibitive.
Limiting or obstructing your team. If so, the rule should be challenged, publicly.

Again, quoting The New People Making:

What do you think about your rules? Are they overt, human [i.e. reasonable] and up to date? Or are they covert, inhuman [i.e. prohibitive, impossible] and out of date? If your rules are mostly of the second variety, I think you realize that you and your family [or team] have some important and necessary work to do. If your rules are of the first category, you are probably all having a ball.

spec-converter 0.0.3

2008-01-19T02:24:00.000-05:00

Inspired by a link Rob sent to a blog entry on converting Test::Unit to Rspec, I added the ability to convert assertions in spec-converter, as follows:

assert !foo with foo.should == false
assert foo > 20 with foo.should > 20
assert foo with foo.should == true
assert_equal y, x with x.should == y
assert_false foo with foo.should == false
assert_nil foo with foo.should == nil
assert_not_nil foo with foo.should.not == nil
assert_true foo with foo.should == true

Enjoy your conversion. ;)

If software could make resolutions...

2008-01-18T22:39:00.001-05:00

Two weeks ago I got what at first glance was yet another electronic greeting, the sort I've come to barely look at for couple of reasons: 1) like everyone else, I never seem to have enough time for everything, and 2) I guess I've become jaded - if someone wants to say hi, I'd rather get a personalized SMS or one sentence email than getting yet another irrelevant "funny" greeting lacking personality. Seconds after hitting the delete button I restored it from my trash to visit later.

I finally got around to it this evening while catching up on my email, curious as to why I had undeleted it. For one, it's simple, with lots of white space and only two, clear links: one smack in the middle and an unsubscribe link - noteworthy because unlike most unsubscribe links, it was obvious.

For another it was from Cooper, the interaction design firm. Over the holidays I'd read Alan Cooper's provocative The Insane are Running the Asylum which resonated with me. (Just ask the folks at work who must be tired of me ranting, "what do you get when you cross a phone with a computer? A computer!" A phone that takes 3 minutes to reboot is more computer than phone, no matter what it looks like.)

I then clicked the link and was pleasantly surprised, for what I found was a short, witty presentation with thoughtful design tips, paired with music composed by Philip Glass. The tips included:

Remember users' preferences.
Aesthetics matter.
Stop dialog-boxing your users.
Communicate with them.
Don't follow, lead.

But don't settle for my summary of it, check it out for yourself.

These tips are indicative of the ideas in his books. The Inmates are Running the Asylum lucidly illustrates various problems that arise when design is merely an afterthought. (Note: his primary focus is on interaction, not aesthetics.)

One such problem is one I alluded to earlier, about the convergence of various electronics with computers. When everyone else's focus is on technology and features rather than on user interaction, Apple handily beats them at their own game time and again. By the by, I contend that this is not because Apple is doing interaction design well as it is because everyone else isn't doing any.

The Insane are Running the Asylum also contained an intriguing discussion of confirmation dialog boxes. Alan points out that confirmation dialog boxes were a misguided "solution" to a user losing their data. By adding a dialog box, such a loss was no longer due to poor design, instead it became the user's fault. Why these miserable dialog boxes persist in the days of unlimited undo and Recycle bin recovery is beyond me.

About Face (which I am still reading) focuses on the how instead of the why of interaction design. It's an interaction design tome. (I want to point out that it includes an excellent primer on business analysis, covering persona and scenario composition.) It distinguishes between implementation, mental and represented models. Simply, the implementation model is the set of classes that encodes the business domain, the mental model is the user's picture of the domain and the represented model is the way the implementation model is presented to the user.

This is in stark contrast to Domain Driven Design's "One Team, One Language" mantra. By insisting that the implementation must match up with the mental model, it can make our job of building software even more difficult than inherently is. Or we do the reverse, forcing the implementation model on our user, who thank you very much, already understands her business and will vehemently resent being told what her business really entails.

By introducing a represented model, we acknowledge that a mental and an implementation model are not equivalent. The represented model, the result of interaction design, can map from one to the other, facilitating usage and implementation.

If software could make resolutions, it might resolve to be considerate. Interaction design is part of what will get us there.

spec_converter released

2008-01-04T22:12:00.000-05:00

Tired of converting your Test::Unit tests over to test/spec specs by hand? So were we. So we made it as easy as 1,2,3:


sudo gem install spec-converter
cd ~/work/my_project
spec_converter

Note that it works on files in place, so be sure to check in or backup first!

It only does the basics right now, converting old style specs to new(context with describe, spec with it) and things like:


def setup
  @o = Object.new
end
def test_should_do_something_cool
  assert_equal 1+1, 2
end

to:


before do
  @o = Object.new
end
it "should do something cool" do
  assert_equal 1+1, 2
end

See its spec for a full list of features. If you'd like to grab the latest, get it at the subversion repository.

Joining the 5%

2007-12-28T12:11:00.000-05:00

In a compelling speech by Bruce Eckel:

... Roughly 80% of programmers don't read books, don't go to conferences, don't continue learning, don't do anything but what they covered in college. Maybe they've gotten a job in a big company where they can do the same thing over and over. The other 20% struggle with their profession: they read, try to learn things, listen to podcasts, go to user group meetings and sometimes a conference. 80% of this 20% are not very successful yet; they're still beginning, still trying. The other 20% of this 20% -- that's about 5% of the whole who are 20x more productive.
So how do you become one of these mythical 5%?
These people are not those who can remember all the moves and have fingers that fly over the keyboard erupting system commands. In my experience those in the 5% must struggle to get there, and struggle to stay there, and it's the process of continuous learning that makes the difference.

It took me a long time to realize that there was such a significant productivity difference. It took me longer still to realize that I could - and should - aspire to achieving that increased level of productivity, and that it wasn't based on innate abilities or otherwise fixed. Bruce lists some things to do to get there:

Read. A lot. [Books rife with advice on how to grow as a technical person include Jerry's On Becoming a Technical Leader and Secrets of Consulting, the Prags' The Pragmatic Programmer, and Chad's My Job Went to India.]
Go to conferences. But be selective about which ones to go to.
Listen to podcasts.
"Using the best tools, techniques, and ideas at your disposal. Always doing your best."
Attend user group meetings.
Keep the big picture in mind: "... people will still spend all their time on one decision while something else might actually have a far greater influence. Architectural decisions, for example."
Remember Jerry's maxim: "no matter what they tell you, it's always a people problem."
Learn the difference between targets and goals (see the excellent Waltzing with Bears). And communicate both.
Never fall for silver bullets.
Keep in mind that "things are the way they are because they got that way ... one logical step at a time."

Tips not in Eckel's speech:

Create passionate users. (The blogosphere isn't the same without you, Kathy!). This means giving interaction design the respect and resources that it deserves.
Learn statistics.
Learn about things that have - apparently - nothing to do with programming. For example, I've learned much from Seth Godin, who taught me the importance of emotions when delivering a speech, marketing yourself and your team, honesty in that marketing and much more.
Learn when to quit and when to stick.
Learn how to communicate better. (Less is more!)
Strive to be the worst member of your team (see My Job Went to India for a good explanation of what this is all about).
"Embrace failure! Seek it out. Learn to love it. That may be the only way any of us will ever be free." And learn from it.
Be curious.
Remember: "no matter what they tell you, it's always a people problem." Because it bears repeating.

I'd like to close the same way Bruce did his speech:

You'll need to make a lot of mistakes in order to figure things out. So be humble, and keep asking questions.

The Carpet Makers

2007-12-25T13:11:00.000-05:00

As you probably know, I love reading. Sometimes, I come across delightfully engaging books. This year that's included the masterful Nassim Taleb's The Black Swan, a provocative look at unexpected, high impact events and Terry Pratchett's Making Money, a fantastical treatise on money and how we interact with it (not to mention a fun excursion into the world of systems thinking and modeling).

Today, I finished another excellent book, The Carpet Makers by Andreas Eschbach (translated from German). It retells an epic story across planets, solar systems and even dimensions that spans millenniums. Yet it manages to weave that story with that of individual characters and their personal plight. The story and his story telling are exciting and engaging making the book difficult to put down. Highly recommended.

Agile Retrospectives

2007-12-25T12:26:00.000-05:00

At Relevance, we recently added a twist to the way we run our retrospective. We have a non-team member lead the meeting. We use this to provide a fresh and impartial perspective give each of a chance to learn about other projects, and introduce more of us to clients. Here, I wanted to share a primary resource we use for planning and running retrospectives.

Some time back, Rob asked me to lead a retrospective for his project. I’d built up several tools over time to help run a retrospective, but I’d never been quite satisfied with the typical format, consisting of the typical exercise asking participants what they felt was going well and what could be done better. So I consulted with Agile Retrospectives: Making Good Teams Great and picked out a few exercises from the book including a Check-In, Team Radar, and Learning Matrix. The book explains the purpose of each exercise, time requirements, a description, necessary materials or preparation as well as an example. Here’s my summary of the Check-In activity:

This exercise is used to set the stage and help participants focus on the retrospective. The format was to go around the room answering the question, "In one or two sentences, what are your hopes for the retrospective?"

And of the Team Radar:

We use this to uncover important factors to the success of the project. It then is used to measure how well the team members think we're doing in each area by ranking each on a scale from 1 to 10 with higher numbers indicating better performance. This can be done in future retrospectives and tracked over the life the project.

(Check out the Selected Activities (pdf) on the book’s web page for examples straight out of the book.)

Such exercises have helped me get a lot more out of retrospectives. Specifically, they've helped our teams get on the same page in terms of important factors to the project and perceptions of how each member thought the team was doing. We've been able to extract and prioritize action items and track team vitals over time. Indeed, we've had projects that have had quick, radical changes in project direction and deliverables due to issues uncovered in such meetings.

What resources do you use for running a retrospective?