©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.
Ideally the detailed user requirements1 documentation describes:
The documentation is read by two audiences:
Systems analysts are sometimes advised to prepare two versions of the requirements documentation:
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.
The following sequence is fairly natural for creating the documentation. With the overview placed at the beginning, it is also natural for the reader.
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.
|Articles on this web site||Recommended Books|
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