Software Project Survival Guide: How to Be Sure Your First Important Project Isn't Your Last. Redmond, Wa.: Microsoft Press, 288 pages, 1997. Retail price: $24.99. ISBN: 1-57231-621-7. Available from Microsoft Press 1-800-MS-PRESS (1-800-677-7377). Buy SPSG from Amazon.com.

Requirements Development 

Software requirements development is the part of the project during which the needs of the customer are gathered and translated into a specification of what the system must do. Requirements development consists of three related activities:

Gathering candidate requirements, which is done by interviewing potential users about the system they want, reviewing competitive products, building interactive prototypes, and so on.

Specifying requirements, which is done by committing the gathered requirements to tangible media, such as a written requirements document, project storyboards, interactive user interface prototype, or some other media.

Analyzing requirements, which is done by looking for commonalties and differences among requirements and breaking them down into their essential characteristics. This is a preliminary design activity and is not discussed further in this chapter.

I depart somewhat from common terminology in referring to these activities as requirements development. These activities are often referred to as "specification," "analysis," or "gathering." I use the word development to emphasize that requirements work is usually not as simple as writing down what key users want the software to do. Requirements are not "out there" in the users’ minds waiting to be gathered like iron ore is in the ground waiting to be mined. Users’ minds are fertile sources of requirements, but the project team must plant the seeds and cultivate them before the requirements can be harvested.

The most difficult part of requirements gathering is not the act of recording what the users want; it is the exploratory, developmental activity of helping users figure out what they want.

Requirements gathering and specification is an open-ended activity. You can consider the project team to be finished with requirements only when it has achieved a clear, stable understanding of what the users want the software to do. Abbreviating requirements activities is a costly mistake. For each requirement that is incorrectly specified, you will pay 50-200 times as much to correct the mistake downstream as you would pay to correct the mistake at requirements time.

This chapter describes an approach to requirements gathering and specification that supports these objectives.

Requirements Development Overview

Here are the general steps I recommend to develop requirements:

1. Identify a set of key end users who collectively have the credibility to define the software the team is building.
2. Interview the end users to create a set of preliminary requirements.
3. Build a simple, interactive user interface prototype.
4. Show the simple user interface prototype to the key end users and solicit their feedback. Continue revising the simple prototype, keeping it simple, showing it the end users, and revising it again until the end users are excited about the software concept.
5. Develop a style guide that codifies the prototype’s look and feel, review it, and put it under change control.
6. Fully extend the prototype until it demonstrates every functional area of the software. Make the prototype broad enough to cover the whole system, but keep it as shallow as possible. It should demonstrate the functional area, not actually implement it.
7. Treat the fully-extended prototype as the baseline specification. Put it under change control. Then require the developed software to match the prototype exactly, except for changes approved through the change control process.
8. Write the detailed end-user documentation based on the prototype. This detailed end-user documentation will become the detailed software specification, and it should also be put under change control.
9. Create a separate, non user interface requirements document for algorithms, interactions with other hardware and software, and so on. Put that document under change control.

This set of steps is weighted heavily toward development of interactive software. If the software is an embedded system that doesn’t have a user interface (such as an automobile cruise control), much of the discussion in this chapter won’t apply to your project.

The following sections describe the nuances of the steps in the requirements process.

Identify a Set of Key End Users

The first step in gathering requirements is to identify a set of users who will provide guidance in defining software requirements. These users must be selected in such a way that if they say that a feature is important, you can believe that it truly is important. Likewise, if they say that a feature can be left out, you should be confident that you truly can leave it out. Be sure to include both power users and average users.

If the project is in-house software, the project leaders can recruit a handful of actual users and make their involvement with the project a part of their job descriptions. If the project is shrink-wrap software, the project leaders can still recruit a handful of actual users, but they’ll need to use their time through more planned, structured interactions.

Soliciting user input is a critical success factor. What if you can’t find any end users and the project grinds to a halt? That might be a blessing in disguise. The project is better off burning just calendar time while you try to find end users than burning both calendar time and money while you build software that users will ultimately reject.

Interview the End Users

An initial set of user interviews should be conducted to elicit a preliminary set of requirements. The preliminary set of requirements is used as the basis for creating the initial, simple user interface prototype.

If we’ve learned one thing in the last 20 years about software developers ability to design software that users like, it’s that software developers by themselves aren’t very good at designing software that users like. But software developers can be very good at helping users discover what they like, because users by themselves aren’t very good at designing software they like either.

Build a Simple User Interface Prototype

Keep the prototype as simple as possible. The point of this activity is to present many different alternatives to the user before you commit much effort to any particular approach. The project team should develop just enough to give the user the look and feel of the software you’re going for, and nothing more. If you want to prototype a report format, for example, don’t even bother to have the UI prototype print the report. The developers should mock up the report in a word processor, and tell the users, "Here’s what will come out when you hit the print button."

If the project is being developed in an environment that doesn’t have good prototyping tools, consider prototyping on a Windows machine and mimicking the look and feel of the target platform. If the real development environment is an IBM mainframe, for example, use Visual Basic to mock up screens with green characters and black backgrounds.

Prototyping activity should be done by a small team of about 1 to 3 senior developers. These developers should be skilled at demonstrating a software’s look and feel with the least amount of work possible. If it takes more than a couple of hours to develop the prototype for any single part of the software, too much work is being done; the prototype is being developed with too much functional depth. Keep it as shallow as possible.

Developing the prototype in this way helps users visualize the software they are specifying, which minimizes the problem of users not knowing what they want until they see it and then changing their minds later in the project. This kind of prototyping minimizes the risk of creeping requirements, which is traditionally one of the most serious risks a software project faces.

Be sure the users understand that the prototype is "just a prototype." One risk of creating a user interface prototype is accidentally raising unrealistic expectations about future progress on the project.

User Paper Storyboards If Possible

One low-tech approach to user interface prototypes is the use of paper storyboards. In this approach, developers or end users start the prototyping process by drawing pictures of the screens, dialogs, toolbars, and other elements they would like the software to have. Developers and end users meet in groups and draw sample screens on flipcharts. They work out the details of the software by simply redrawing the prototype on flipcharts until they reach agreement about the software’s appearance and functionality.

This approach offers several advantages. Users can do some of the work themselves; they don’t have to know how to use prototyping software. Storyboard prototypes can be generated and modified rapidly. They are inexpensive.

Paper storyboards also eliminate some of the most common risks associated with prototyping. On the developer side, they eliminate the risk of needlessly overextending the prototype and of spending too much time fiddling with the prototyping tools. On the user side, storyboards eliminate the problem of users thinking that a realistic-looking prototype is almost the real software.

The one disadvantage of paper storyboards is that some developers and end users simply cannot visualize the software from a paper mockup. This is a significant disadvantage since the strongest reason to create a prototype is to help the users visualize the software that will be built. If you find that paper storyboards aren’t helping the project stakeholders visualize the software, don’t hesitate to revert to electronic prototypes.

Revise the Prototype Until the End Users Are Excited About the Software

The first version of a prototype will rarely satisfy the users’ expectations. Developers should show it to the users with the expectation that the users will have comments that will cause them to revise the prototype. They should explain to the users that the prototype is a work in progress, and that they want their criticism. If the users are confused or think the software will be hard to use, that isn’t the users’ fault; that’s a problem that should be corrected during prototyping, before work on the actual software begins.

Refining the simple prototype until users are excited about it supports creation of software that will ultimately be highly satisfactory to end-users, rather than one that merely "satisfies requirements." It might seem as though developers are spending an inordinate amount of time working on something that will be thrown away, but this upstream activity is a good investment in preventing costly downstream problems.

Prototype development will take more time if the development team is working in a new area (one in which it has less than two years experience) than a familiar area.

This is a good time to remind users that the prototype is "just a prototype." In one organization I worked with, when developers reminded their users that they were seeing "just a prototype," the users started chanting, almost in unison, "and it’s just smoke and mirrors, and it will still take a long time to develop. We know, we know, we’ve heard that before." The users were good natured about the reminder; the developers had done a good job of educating them.

Develop a Style Guide

Once the users have agreed to the general look and feel of the prototype, the developers should create a User Interface Style Guide that sets standards for the application’s look and feel. This should be only a few pages long including screen shots but complete enough to guide remaining work on the prototype. It should include size and placement of standard buttons such as OK, Cancel, and Help; allowable fonts; style of error messages; mnemonics for common operations; adherence to common design standards; and other common elements of the user interface. After it is developed, the User Interface Style Guide should be reviewed and put under change control.

Addressing design style issues early in the project promotes a consistent user interface. It also prevents developers from continually tweaking the user interface and prevents users from requesting arbitrary, late changes to the software when it is finally delivered.

Fully Extend the Prototype

Driving prototype development across the full breadth of the system enables developers to visualize the software to a degree that promotes better architecture and design work. The project’s vision statement enables developers to align their work in a general way; the detailed user interface prototype provides the detailed vision that enables them to align their work in thousands of smaller ways.

Be sure that the prototype truly addresses all of the software’s functionality. Here is a partial list of the functionality that should be represented:

All dialog boxes including standard dialogs such as file open, file save, printing, and so on

All graphical input screens

All graphical and textual outputs

Interactions with the operating system, such as importing and exporting data to the clipboard

Interactions with all third-party products, such as importing and exporting data to other programs, providing components to be embedded in other programs, and so on

At the time the prototype is baselined, it will probably be unclear to the development team whether it is technically feasible to implement some of the specific functionality demonstrated in the prototype. This is a natural aspect of prototyping, since it is easy to prototype functionality that couldn’t be implemented in a million years. (For example you could easily prototype a system that draws a photographically realistic picture based on a textual description typed in by the user, but actually implementing that is well beyond the current or foreseeable state of the art.)

A list of functionality that is at risk should be documented, explained to the end users, signed off, and put under change control. This can be included as a section in the requirements specification. It is a rare project that will not have any functionality in this category, so you should expect to have such a list of "to be determined" areas on your project.

Remember That It’s a Throwaway Prototype

Although the prototype is driven across the full breadth of the software, the emphasis should continue to be on demonstrating functionality with the least possible amount of work. Remember that the prototype is a dead-end. It is a useful dead end, but a dead end nonetheless.

A good prototype is slapped together quickly with programming duct tape and bailing wire. It is like a Hollywood stage set in which the front of a piece of wood is painted to look like a house, but there is no house behind the front piece.

You shouldn’t use a user interface prototype as the basis for real software anymore than you should use a Hollywood stage set as the basis for a real house.

When a prototype is developed in this way, do not under any circumstances use it as the code base for releasable software. It has intentionally been developed to be disposable; trying to use its code in the releasable software is tantamount to trying to build a real house on the foundation of the Hollywood stage set house.

Consider developing the prototype in a programming environment that makes it clear that the prototype code will not find its way into the final software. If the project team is planning to implement the software in C++ or Java, for example, develop the prototype in Visual Basic so that it would be impractical to use it as the basis for the real software.

Treat the Fully-Extended Prototype as the Baseline Specification

At this point the prototype can begin to serve as the reference point that the whole development effort will align on. For it to serve that function, it must be stable, and the team must commit to develop software that exactly matches the prototype. Have the project’s decision makers sign off on it and put it under change control. The organization will base its estimates, plans, staffing, architecture, designs, and development work on it. It is both appropriate and necessary that the decision makers commit to it and that changes to it be systematically controlled.

Systematically controlling changes does not mean "freezing" the requirements. Instead, the project is making a commitment to handle further changes to the software in strategic ways that support the project’s objectives. The most common alternative approach is to handle changes indiscriminately, with no strategic plan, in ways that ultimately impair the project’s ability to achieve its objectives.

Once the prototype has been baselined, it provides several valuable benefits. In addition to the requirements stability benefits already described, a full UI prototype enables end-user documentation and test plans to be developed in parallel with architecture, design, and implementation work. These activities often end up on the critical path otherwise because they cannot be started until implementation is well underway.

Write the Detailed End-User Documentation Based on the Prototype

Sometime prior to placing the prototype under configuration management, work can begin on a detailed user documentation (User Manual/Spec). This is the documentation that will eventually be delivered to the software’s end users. Typically, this documentation is developed at the end of the project, but in this book’s approach it is developed near the beginning.

Some people might object that creating full-up end user documentation and keeping it up to date takes more time than creating a purely technical requirements spec. That’s true, as far as the just the requirements spec is concerned, but it is often cheaper than creating end user documentation and a full technical spec.

Developing end-user documentation first eliminates the necessity of producing a standalone technical specification. The document that is produced is more understandable to end users than is the typical technical spec, which improves the quality of end-user feedback about the software. The early development of the end-user documentation fleshes out the software demonstrated by the UI prototype, filling in gaps, and flushing out inconsistencies.

This approach involves end-user advocates in the project early on—technical writers tend to be good at representing the end user’s point of view, often with more sophistication than the end users themselves are capable of.

This kind of spec is more likely to be kept up to date. Many software specifications become "write-only" documents—they are written at requirements time to satisfy the project plan’s edict to create a software specification, but they aren’t kept up to date with requirements changes and often aren’t even used after they are written. They are too monolithic and too boring. In contrast, when the development team knows that the "spec" will ultimately be released to end-users, the incentive to keep it up to date is greater.

This approach also solves the perennial problem of whether the requirements spec should cover the "what" or the "how." If the tech writers think the end-users need to know it, it should be in the User Manual/Spec. Anything that’s not covered in the User Manual/Spec is left to the developers’ discretion.

Many products contain complex documentation sets that include a user manual, tutorial, reference, and on-line help. The only one of these that needs to be created at this stage is the document that describes the end-to-end functionality of the software. If such a component is envisioned as part of the on-line help, developing that on-line help document first will provide the reference that is most usable by the development team.

Create a Separate, Non User Interface Requirements Document

The approach described in this chapter works best for user intensive, small- to medium-sized projects. Most projects will have some functionality that cannot be specified in enough detail in a user interface prototype or a user manual to provide guidance for design and implementation. Specifications of detailed algorithms, interactions with other hardware and software, performance requirements, memory usage, and other less visible requirements can be recorded in a separate requirements document (or as an appendix to the User Manual/Specification). After its initial development, that document (or appendix) will need to be reviewed, baselined, and placed under change control.