Monday, October 24, 2011

Remote README and debugging

I've been doing a fair amount of work lately with people who are remote. We're not in the same city or even in the same time zone, but we're working on the same project and using each other's code. It's not always easy, but we're making progress.

In order to do this successfully, we have two simple rules:

  1. Write a README
  2. Show me what you see
Let's talk about a README for a minute. I know that when I'm done writing some piece of code, it's intuitive and obvious how to use it.... to me. That doesn't mean it's obvious to anyone else on the planet. So I write a README that tells people how to use this thing I've created. The more background I share with someone, the shorter the README can be. If I'm adding a small feature to a Rails application and my colleague is a Rails engineer who also knows the application, I can probably have a README that says, "I added a spec to show it - check out the commit." He'll know to go look at my latest commit, where to do that, how to understand the rspec test I wrote, etc. With less shared background, the README gets more detailed. For example, I wrote a python script recently and handed it off to an engineer to run. The catch, the engineer doesn't know python. So my README was very detailed, including how to set up Python, how to check out the project, how to run the exact command line he needed, and an example of a successful result. Why? There's not very much shared background, so I can't assume he would do the same things I did, have the same setup I do, or read output the same way. This is no denigration of the engineer I was working with; he simply has a different background. (You should have seen the README he sent me for the .NET utility he wrote - I had none of that background!)

All in all, it's pretty simple. Write a README telling someone what you did. The less they know about how you think and how you do things, the more detailed the README should be.

There's some bad news, though. No matter how good your README, someone's going to have trouble following it one day. This is where the second rule comes in. Always show me what you see. It's a classic user call for help: "I tried it and I got an error!". We engineers do it, too, and it really doesn't help solve the problem.

So if we run into a problem and need help, we have to show each other what we're seeing. On a command line, that means we run some basic helpful things and send the console output to the user. Let's take that python script (which didn't go right for the user the first time despite the great README). In order to help me figure out why it was working for me and not for him, he sent me a basic console output that showed this (names changed to protect the innocent):
$ pwd
$ ls
$ python --version
Python 2.7.2
$ git status
# On branch master
nothing to commit (working directory clean)
$ git pull
Already up-to-date.
$ command -to -run the script


This way I have a lot of information. I can already tell:
  • what version of python he's running
  • the exact error he got
  • where his source tree is located and if there's anything funny about it
  • that he's on mac, not Windows
  • that he doesn't have any interfering local changes
  • how he ran the script, including arguments and options
When we're remote from each other, communication is somewhat high latency; there are minutes between communication at a minimum, and sometimes more. We don't want to go back and forth many times; fewer is faster. So, he shows me what he sees and that makes it much more likely I'll figure out what's different in fewer tries. And then we can both get back to work faster!

No comments:

Post a Comment