For the basic idea, we've set up a Basecamp project, and I'm putting stories in there. The stories are high level, because we've all worked together for long enough we can communicate in shorthand. We can say, "let's build user login based on email and password" and understand that implies session timeout, hiding everything behind the login unless we specifically mention otherwise, etc. And then there are the nitpicky little details. What are the requirements for password strength? What are the error messages the user should see when they fail to login?
For those, we're communicating through code. Yes, code can be communication, too.
I'm a tester, so we're communicating through tests for these types of little details. After all, I'd have to write these tests anyway. So I just write them a little earlier, check them in (failing), and the person writing login simply makes them pass. For the record, I didn't come up with this idea. It's been around for years called test driven development and behavior driven development (and probably several other things).
I've learned a few things over the years that are helping to make this a success, though. It's far from guaranteed.
Communicate through code when:
- The audience is engineers. No code is really English* so use code only when communicating with others who are comfortable in code - developers, testers, some analysts.
- The requirements are small and concrete. If there is a lot of interaction or a bigger picture, then express it in some way that describes the bigger picture. This is almost certainly not a single test or a series of tests. Use tests to communicate password strength requirements; don't use them to define an interface between two systems (that one probably wants a data flow diagram to make it intelligible to others).
- You're not co-located. When you're in Boston and the other person on the project is in San Francisco, you can't talk, and writing things down in code is easier than writing code and also something else to communicate all the details.
- You want one location for information. You will eventually have the information in code anyway, in the form of implementation and tests. If you only put it in code then you'll save some time trying to maintain and reconcile multiple copies of the information.
Don't communicate through code when:
- You're talking big picture. Vision is a large, shimmering, wonderful thing. Express it in words, drawings, videos, and other things that can show your excitement. Code is many things, but it doesn't convey excitement.
- You need to communicate with outsiders. If they can't see your code, then they can't get information from it.
- You need to communicate with non-coders. I don't speak German to people who don't speak German; they're simply not going to understand. The same thing applies to speaking code to people who can't read code.
Communicating through code is one of those things that sounds like a great idea. Often, it is a great idea. Sometimes, it's a pretty terrible idea. As with any communication, consider your audience, think about why you're communicating, and then decide if code is an appropriate communication mechanism.
* I had a conversation recently with James Bach and a few others about this specific topic. Code isn't English, no matter how many English words is uses and how much it really does kind of look like English. There are far more rules and restrictions in code than in English (or any other human language). Credit goes to James for helping me think about this one a little more.