Handling Requirements

---

Depending on the project, coming up with your initial feature set can ease into a formal process for handling requirements. One thing needs to be clear right up front, though: Not every software project needs a formal requirements process. In general, I’ve found that requirements management is more important when the requirements come from someone other than the software developer. If you’re building software to implement your own vision, you can probably get by without anything more than a mind map or feature list to cover your product’s requirements. But if you’re building an application to handle data entry for an insurance office, you’re probably not an expert in the problem domain (that is, in the details of the business of selling insurance). In that case, paying more formal attention to requirements can save you lots of grief down the road.

Tip

As a middle path, you might like to track your product’s requirements with a bug-tracking tool. I’ll talk more about this in Chapter 9, “Tracking and Squashing Bugs.”

Defining Requirements

Broadly speaking, the requirements for a piece of software define what the software should do. But it helps to have a framework for classifying requirements. One useful framework comes from Karl Wiegers’ book Software Requirements (Microsoft Press, 2003). Wiegers distinguishes four types of requirements in his taxonomy:

• Business requirements High-level objectives of the organization or customer who requests the system.

• User requirements User goals or tasks that the users must be able to perform with the product.

• Functional requirements Software functionality that the developers must build into the product to enable users to accomplish their tasks, thereby satisfying the business requirements.

• System requirements Top-level requirements for a product containing multiple subsystems. Note that not all of the subsystems will be software!

TECHNOLOGY TRAP: This Year’s Model

Developers tend to be a bit like magpies. When we see something new and bright, our instinctive reaction is to cart it back to our nests. “Ooooh, shiny!” could be the slogan on our coat of arms.

One place this is evident is in the way that fads sweep the development universe. For example, take peer-to-peer. For a while, it seemed as if everyone was building their software to be peer-to-peer enabled. “Our product will be the best peer-to-peer enabled fish scaler on the market” isn’t a real elevator pitch, but it surely could have been. There are plenty of other technology fads that I’d put in this category, for example:

• Distributed computing

• Banner-ad supported

• Web services

Now, certainly all of these are useful technologies for some things. But they clearly don’t belong in every single product on the market. Particularly when you’re a small shop, it’s important to concentrate on adding real value, rather than simply buzzword compliance. Restraining yourself will also prevent you from wasting time learning a new technology, only to find that it’s a dead end (anyone remember Data Reports from Visual Basic 6?).

Here’s a tip: When you read an article about some hot new technology, resist the temptation to immediately add it to your code. Instead, write it down on a sticky note and stick it to your monitor. If your application really needs a distributed reflection-based plug-in API, it will still need it in the morning. If not, it’s a lot easier to rip off the sticky note than to roll back the code changes.

Wiegers divides the process of working with these requirements into requirements development and requirements management. Requirements development further divides into a complex set of elicitation, analysis, specification, and validation activities, with feedback loops between them. After requirements development has teased out the requirements for a product, requirements management entails the process of coming to an agreement with the customer as to what the requirements are, and tracking the progress of the product to meet those requirements.

Warning

Requirements are rarely static. If you’re building software for an external customer, make sure you and the customer agree on how the requirements can be amended, and decide up front who bears the burden of any additional costs.

Eliciting Requirements Checklist

If you’re working with an external customer, this checklist will help you elicit the requirements for the software:

• Talk to the actual end users of the software. Ask them what they expect the software to do.

• Watch how the end users perform their job now. Make sure you understand how the software will change things.

• Write a vision and scope document, explaining what’s a part of the project and (equally important) what is not. Make sure the customer agrees with you.

• Hold an informal group discussion with the users over lunch or a night out. People will speak up in a group of their peers even when they won’t tell you things one on one.

• Document the requirements you determine in plain English, and then check with the users to see if they make sense.

• If you’re replacing existing software, find out what’s wrong with the current system. Your requirements will often boil down to fixing the problems.

• Arrange the requirements in priority order and make sure the customer agrees on the priority.

At the end of the requirements elicitation process, you should know what the software will do. Just as important, the customer should have confidence that you understand their requirements.

Eliciting and Documenting Requirements

If you’re writing software for yourself, eliciting requirements (often called needs assessment) is simply a matter of writing down what you think the software should do. If you’re dealing with an external customer, the process can be much more complex. There’s no alternative to getting the customer to tell you what the requirements are, but you have many ways to go about this. You might observe them at work, exchange frequent e-mails, or even convene a formal requirements workshop. For this book, I’m going to assume that you are your own customer, and hence, a formal requirements elicitation process is unnecessary. If you’re working for an external customer, the sidebar “Eliciting Requirements Checklist” will help you get started, but you should also read Software Requirements or another book on the subject.

The issue of documenting requirements still remains. One useful tool for a formal requirements document is the use case. A use case describes one or more interactions between an external actor (which might be a person or another application) and your application. Here’s a partial list of use cases for Document Tracker:

• Download Software

• Annotate Software

• Rate Software

• Publish Software List

• Search for Software

Two or three words isn’t much in the way of documentation, of course. To seriously employ use cases for requirements, you’ll need a more formal document for each use case. Typical contents of a use case document include:

1. A unique identifier for the use case

2. The use case name

3. A short text description

4. A list of preconditions that must be satisfied before the use case can start

5. A list of postconditions that must be satisfied when the use case ends

6. A numbered list of steps that are carried out in the use case

See the sidebar “A Download Tracker Use Case” for one simple use case document.

A Download Tracker Use Case

Use Case ID: UC-1

Use Case Name: Download Software

Description: The user initiates a software download by notifying Download Tracker of the desired file. Download Tracker prompts for a download location and identifying information. When the download is completed, Download Tracker displays a success message.

Preconditions:

1. Download Tracker is already running.

Postconditions:

1. Software is stored on hard drive.

2. Database contains a record for the software.

Normal Course:

1. User drags a URL from Internet Explorer and drops it on the Download Tracker tray icon (see Alternative Courses 1.1 and 1.2).

2. Download Tracker prompts for a download location, starting from its default directory.

3. User confirms download location.

4. Download Tracker initiates download.

5. Download Tracker prompts for identifying information such as program name, description, and keywords.

6. User enters desired information and clicks OK.

7. Download Tracker creates and saves database record.

8. Download Tracker notifies user when download is complete.

Alternative Courses:

1.1 (alternative to step 1): User pastes a URL to the Clipboard, then right-clicks on Download Tracker icon and selects Download From Clipboard. Continue with step 2 of Normal Course.

1.2 (alternative to step 1): User right-clicks on Download Tracker icon, selects Download URL, and enters a URL. Continue with step 2 of Normal Course.

Exceptions:

E1. URL is not valid

1. Download Tracker displays a message if it cannot download from the specified URL.

Note

As you can probably guess, people have written software specifically for requirements management. Most of these packages are directed at large organizations and require a fairly serious commitment of time and resources to install and master. You’ll find a comprehensive list on the Requirements Management website at www.jiludwig.com/Requirements_Management_Tools.html. For small projects, you’ll probably do just as well to write your use cases in Word or Excel.

---