REQ01 Teaching Tips

Informal Requirements Specification

Developed with support from the National Science Foundation

Version 1.0

Teaching tips

  1. This module is appropriate for inclusion in a first course in software requirements or in a course that applies formal methods to the documentation and analysis of software requirements. The example used in the module exercise can also be used as a vehicle to work with formal specification and modeling, as in module REQ02. A primary purpose of this module on informal specification is to give the students an opportunity to see just how difficult it is to completely specify the requirements for even a fairly well understood system. Many students will underestimate the difficulty of this module's exercise, and it is not uncommon for their first attempts to be incomplete and to contain glaring omissions.
  2. This module is designed to be presented in two class sessions, with the exercise done between the two sessions. The first session presents the example system and exercise, leading into a class discussion to prepare for the exercise. The second session follows up on the completed exercise.
  3. In the first class session, distribute the exercise to the students. Briefly (10 minutes), present the system description, clarifying terminology and system components. It may be helpful to draw diagrams of the buttons and indicators inside the elevators and on each floor.
  4. Briefly (10 minutes), present some techniques or elements that might be used in an informal requirements specification. (If the module is used in the context of a course that incorporates formal methods, make it clear that this exercise should not use formal notation.) Some examples are:
  5. Spend 20-30 minutes leading a class discussion of the elevator system. The following questions can be used to facilitate the discussion:
    1. What is the right level of abstraction for the requirements to be specified?
      Should the specification deal explicitly with the timing of elevator door opening and closing?
      Is it necessary to specify time intervals for elevator movement?
    2. What are the primary operations that should be specified?
    3. What are the significant system inputs?
    4. What decisions must be made by the software that will control the elevator system? What are the factors that go into making each type of decision?
  6. It may be helpful to have students work in groups of 2-3 members to discuss the above questions, and then report back to the class on significant conclusions and remaining questions.
  7. The instructor should play the role of a primary system stakeholder or client representative to address ambiguities in the written system description and to answer questions from students about the system requirements.
  8. Based on the class discussion, it may be desirable for the instructor to document in writing the "client" answers and clarifications elicited by student questions.
  9. In the second class session, after the exercise reports have been submitted (and, if possible, evaluated), the instructor should identify areas of potential or actual difficulty in completing the exercise, and discuss the experience with the students. Some of these issues are discussed in the exercise key.
  10. If time permits, a useful strategy would be to have each student team critique the specification prepared by another team. Together, the students could identify common difficulties and explore ways in which the specifications could be improved.

Note

If you use this module in the context of a course that will continue into formal modeling using the Z notation, it may be desirable to have the students use LaTeX to prepare the informal specification for the exercise in this module. This will help to prepare students to use LaTeX as a way of creating specifications that include formal Z text, using special commands for the Z constructs.