Monday, July 26, 2010

Requirements Tracking For Total Slobs

I'm now working on an iPhone/mobile startup with just a handful of people, and we typically get things done via shouts, IMs, and emails. This works for us, but I used to work at a company which did things *much* more formally. We will refer to this way of doing things as (drumroll) The Process.

The Process goes as follows: Product Managers generate Functional Requirements which go to the Engineers which turn these into Design Requirements which go to the Developers which develop The Product which goes to QA who uses the Design Requirements to create a Test Plan which then gets sent to Integration Teams which use the Documentation generated from the Design Requirements to make the Installation Guide which then results in the Customer getting ... well, something.

This is a little heavyweight for the standard indie dev shop, but there's a good practice hidden here, which is the generation of Requirements. Why would you want to make actual Requirements when DESIGN.TXT in your home directory will do just fine? There are several reasons:
  • They encourage you to record design decisions, and act as high-level code documentation.
  • They give you a way to generate test plans - each requirement should be a testable feature of the product.
  • When doing a port to another platform, they let you know when you're done (when all the requirements are checked off)
  • They let the test team know when they're done (when all the requirements are checked off)
These all boil down to "scoping" your product. Any external party can look at the requirements of your application and get the gist of what's going on without looking at code, and if you do it right, they can test/document/port/translate/regress/whatever and know that they haven't missed anything.

Of course, no one is really going to go through much extra effort generating documentation when they could be making apps and making money. That's foolish. That's why I'm going to show you my bone-simple Requirements Generation Technique. Watch closely!

1. A requirement is defined in a source file (.c, .cpp, .m, .java etc) with a code comment. Here is an example:

// Requirement: When a Butterball is hit with a bullet, split it into two Niblets.

2. Generating a design document is done as follows:

% find . -name '*.[cm]' -print0 | xargs -0 grep Requirement: > design.txt

3. Doing a "Gap Analysis" (comparing two design docs) is done as follows:

% sdiff design1.txt design2.txt

With a little effort, you can pipe requirements to CSV files and upload to Google Docs so other team members can review, make test plans, etc.

Congratulations! You've just replaced thousands of dollars of expensive requirements-tracking tools and at least three middle managers! You've also taken a step to better documenting your code and your product so others can more easily play in your sandbox. You don't need an overweight version of The Process like our example bureaucratic organization, but it helps to have a little organization in whatever you do.