May's issue of the month pointed out serious flaws in some recent trends in documenting user requirements. Several readers asked me to follow up with some positive recommendations on what should be in a complete and rigorous user-requirements specification.
This article is the first such recommendation. If you find it helpful, let me know and I'll continue. On the other hand, if you disagree with this recommendation, I'll be glad to publish your alternative suggestions.
I recently reviewed yet another in-trouble system development project for a client. The project had suffered a sequence of missed target dates and cost overruns, and everyone understood that heads would roll if they should fail to make the latest "deadline" a couple of months away.
I began by examining the functional requirements. The project team had amassed over 250 use-cases along with a list of several hundred discrete requirements in a half-dozen categories.
I asked first to see the system output specifications, that is the reports and displays that users see. My request turned out to be impossible to satisfy:
So, there was no written record of what information the proposed new information system was to produce. I couldn't review them. The sponsoring users not only hadn't reviewed them, but were unaware that the omission was a serious problem.
Is that experience unusual? Not at all. Use-cases1 and discrete requirements lists, supported by popular C.A.S.E.2 tools, are driving out many components of a well-structured system specification.
Not only are system output specifications one of the most important components of a detailed requirements specification, but they're also
Fortunately, system output specifications are also very easy for user-reviewers to understand without special orientation. Non-technical users find them natural and close to their interests and expectations.
Once the systems analyst knows exactly what information is to be produced by the system, he or she will be able:
Some systems analysis textbooks3 and packaged life-cycle methodologies contain forms or templates for specifying system outputs. The good ones call for at least the following information:
- What is this output used for?
- What purpose does it serve?
|Distribution / access||Answers questions:
- Who (role in the user organization) gets this report?
- Who is authorized to see this display?
|Medium (optional)||Paper report, screen display, or other.|
|Content||List of component data items (fields), each of which is either:
- Defined precisely in the project data dictionary or
- A simple formula applied to items in the data dictionary.
This is the most important section of the output specification. It addresses the very purpose of the system.
|Sequence||List of fields defining the sorting sequence of the output.|
|Volume||Average and maximum number of lines, pages, etc.|
|Frequency||How often the output is produced, e.g. daily,
(If on-demand state average and maximum.)
|Audit, security, & privacy
|Any restrictions and constraints on the production, circulation, and ultimate disposition.|
The best advice to the systems analyst is: Don't do it unless the user-reviewers can't otherwise understand your output specification.
From the point of view of user requirements, the content specification described above is, in theory, sufficient. The layout and format of screens and reports is logically part of internal system design, which occurs after the requirements are as complete as possible and approved by the sponsoring user. If we constrain layouts and formats prematurely we run the risk of:
Nevertheless, some user-reviewers find it easier to grasp the essence of a system output when they see what it will actually look like. Sample report pages, screen shots, and input-output prototypes are ways of conveying the look-and-feel to the reviewers. Such samples may supplement but must not take the place of the content specifications described earlier.
See the July addendum to this article.
1 - A recent revival of the sequential narrative
style of specification writing, popular in the 1960s.
2 - Computer Assisted Software Engineering.
3 - Alas, most do not. Even the classic texts on structured systems analysis placed insufficient emphasis on output definition. The UML-based systems analysis books I'm acquainted with are especially hopeless in this regard. Some books devote chapters to how to design outputs but tell the reader nothing about how to specify them. If you know of a good reference, let me know.