Requirements When the Field Isn't Green

Most books and articles on software requirements are written as though you're gathering requirements for a brand-new product-what's sometimes called a "green-field" project.

In reality, few people have that opportunity on every project. Many developers work on maintenance projects, constrained by a legacy system's current reality or previous incarnations of an evolving product. In such a project you're usually adding new features to existing systems, modifying functionality to comply with updated business rules, or bolting extensions onto commercial packages. Too often, you can't find anything resembling a requirements specification for the system you're enhancing. It's not unusual to have to maintain a system without adequate documentation, with the original developers who held all the critical information in their heads being long gone.

If you're in such a situation, you might be tempted to reject the requirements literature as irrelevant. Not so! You can apply several useful requirements engineering methods even in these situations-even when you're squeezing new functionality into an unruly product in a documentation vacuum. The same ideas apply to iterative development projects doing a series of successive releases. Here I'll describe seven principles to help you deal with requirements issues in such maintenance situations. We'll also look at ways in which thoughtfully applied requirements development and management practices can help you improve both your product quality and your ability to perform future maintenance.

1. Don't Dig Your Hole Any Deeper
Let's do a little survey. When people on your project team have needed to change the current functionality of a product, how often have they had to reverse-engineer from the code enough knowledge of an ill-documented system to let them make the change? I thought so. Nearly every maintainer has had to do this at some time.

Now a follow-up question (and I'm not trying to embarrass anyone here): How often did your team capture what they learned from such reverse engineering in a shareable way?

Just as I suspected. When we gain some insights from painfully exploring an existing black box system, we rarely take the time to record them for posterity. And in this case "posterity" is no farther away than you or your colleagues having to work on the same system in a few months. So it's worth taking some time to document your newly discovered understanding in the form of requirements or design descriptions.

This will put your team in a position to perform future enhancements more efficiently. If you're performing maintenance in what's already an information void, vow to not dig the black hole you're in any deeper as you add enhancements.

Perhaps your current system is a shapeless mass of history and mystery, like the one in Figure 1, and you've been asked to contribute some new functionality. Begin by recording the new requirements in a structured, if partial, software requirements specification (SRS) or a requirements management tool. When you add the extra functionality, you'll have to figure out how new screens or features will interface to the existing system (as illustrated by Figure 1's bridges between the existing system and the new functionality). This analysis in turn provides a bit of insight into the related areas of your current system (labeled as insight zones in Figure 1). This is the new knowledge you want to capture.

One technique you might find useful for representing this knowledge is to draw a dialog map-a user interface architecture--for the new screens you have to add, showing the navigation connections to and from existing display elements.

By building a requirements representation that includes portions of the current system, you've accomplished two things. First, you've halted