My classmate Wan just wrote up an insightful piece about software specifications from a project management perspective, making some great points about software development in general.

I couldn’t agree more with him that it’s vital for software developers to be collocated with product managers, testers, and everyone else they need to communicate with on a regular basis. Fundamentally, developing software is all about managing information at varying levels of abstraction. As developers, it can be all too easy to forget about the importance of good communication with our teammates.

But software specifications are more than just a form of communication between people. They also serve as a form of documentation, which in my experience, is the kind of information that software developers are worst at managing. One of the most dangerous things you can do with any form of documentation is to forget that it’s really an evolving document. During the development of any piece of software, its behaviour is in a constant state of change. If your documentation doesn’t change as well, you’ll be left with something that’s worthless, broken or both. To quote Norm Schryer:

When the code and the comments disagree, both are probably wrong.

It’s hard enough to keep documentation consistent with your software when it’s inline with your source code. Keeping software specifications up to date is even harder, especially if the only copy you’ve got access to is on paper. That’s why most agile methodologies recommend using unit tests in place of specifications, to force developers to keep things consistent.

I’m not advocating that all specifications should be scrapped and replaced by tests. Documentation is a vital form of communication with the future developers, product managers, testers and users of your software; not to mention with yourself in a year. The problem isn’t that we have to write it, it’s that we let it become inconsistent with the code.

Taking Wan’s ideas a step further, I think it’s important to do more than just collocate your team. You need to collocate your information as well, and keep your specifications as close to your source code as possible. Like a group of people, information is harder to manage if it’s scattered all over the place.