Guidelines for Requirements Phase Deliverables

©2003 Information Disciplines, Inc., Chicago

If you find these guidelines useful, feel free to use them on your projects. Instructors may use them as course handouts, as long as the copyright credit is included. Do not, however, publish or sell any of this material outside your own organization without our written consent. If in doubt, contact the author (see home page for telephone and E-mail information.)

In response to several articles critical of some recent trends in specifying detailed user requirements, several readers asked for some positive recommendations on preparing such documentation. Our June, 2003, issue of the month offered a sample component of such guidelines, and several readers responded with requests to complete the set. The following is a condensation of material originally developed for IDI's systems analysis courses and client consulting work.

Purpose, authors, and audience

Ideally the detailed user requirements1 documentation describes:

Requirements documentation is usually prepared by one or more systems analysts with participation by representatives of the sponsoring user organization(s).

The documentation is read by two audiences:

  1. Representatives of the sponsoring user organization, who are both

  2. The developers2 who will build the system, especially the senior designer or chief programmer.

Warning

Systems analysts are sometimes advised to prepare two versions of the requirements documentation:

  • one for the user reviewers, using business-oriented terminology and intuitively obvious diagrams, and
  • another for the developers, using computer-oriented terminology and technical diagrams.
That's tempting, because it lets the analyst avoid some difficult communication issues, but it carries a serious, potentially catastrophic risk. The project is then dependent on the absolute consistency of the two versions. Any discrepancies, including seemingly innocent ambiguities, may go undetected until the late stages of testing.

Never do that. No matter how skillful and conscientious a systems analyst may be, a non-trivial project can't afford to put all its eggs in that one basket and depend on one or two systems analysts to assure absolute consistency. Prepare one set of detailed user requirements documentation, in terms that both audiences can thoroughly understand.

The requirements documentation then serves as a contract between the sponsoring users and the developers. That doesn't mean, of course, that the specifications are frozen after the users approve them. We know that changing economic conditions, new business opportunities, or fresh insights can introduce changes at any phase of the project.

Recommended contents of requirements phase deliverables

The following sequence is fairly natural for creating the documentation. With the overview placed at the beginning, it is also natural for the reader.

  1. Specifying System Outputs -- June, 2003, Issue of the Month
  2. Defining Data Items
  3. Specifying System Inputs and Transactions
  4. Tying it all together: data-flow diagrams or equivalent.
  5. Specifying business rules, logic, processes, and Algorithms

Coming soon

  1. Designing the Data Model (logical data base)
  2. Specifying Interfaces with Other Systems
  3. Specifying Audit, Privacy, and Security
  4. Specifying Constraints
  5. Writing the System Purpose and Overview

A fundamental rule for systems analysts

Although experience shows that the above structure is a sound basis for capturing, presenting, and maintaining detailed user requirements, many systems analysts, including some respected textbook authors, prefer different techniques, for example the "use-case-driven" approach. Those arguments are interesting, but in the end irrelevant.

The first criterion remains understandability in complete detail by the intended audiences. In particular, if the user representatives, after a reasonable good-faith effort, do not thoroughly understand the requirements documentation, it is the systems analyst's responsibility to revise or restructure the documentation so that they can understand it. Different users' backgrounds and skills demand different kinds of presentation. You may feel absolutely certain that the structure or diagramming techniques you've chosen are the "best practice" or "state of the art" in requirements documentation, but if they don't communicate effectively and unambiguously to your user community, you're obliged to abandon some of them and devise a suitable alternative.

Background reading

Articles on this web site Recommended Books
  • James and Susan Robertson: Complete Systems Analysis -- see review for details. Caution: Don't confuse this execellent book with a later "requirements" book by the same authors.
  • David Hay: Requirements Analysis -- From Business Views to Architecture, 2003, Prentice Hall, ISBN 013-028228-6 (review pending).
  • Igor Hawryszkiewycz: Introduction to Systems Analysis and Design, 1998, Prentice Hall, ISBN 013-896887-X.
1 -- Alternative names for these documentation deliverables include "Functional Specifications", "Business System Design", "External System Design" and simply "System Specification".

2 -- We use the term "developers" in the most general sense of the I.T. professionals who build and install the system, whether they develop custom software (programming) or purchase one or more application software products.

Return to IDI home page

Last modified 30 June, 2003