Chapter 16       Detailing The requirements

Review of how we got here:

This is the final step in the requirements process. For simple applications, it may be sufficient to stop at modeling the application use cases, and tag the use case steps (and supporting information) as the application requirements.

For a more rigorous set of requirements, we modeled the use case data with class diagrams, Then we applied the use case steps to each class to derive states of the application. Then we model the class states and classes with sequence diagrams and traced these back to the use case steps, by mapping the steps to the messages between classes that cause state changes to occur. These message are added to the appropriate class as class operations.

In this final stage we derive the application functional requirements in textual form directly from the class operations, using a textual requirements template, of the form:

[Precondition][1], [Initiating Actor], [Trigger], [[Output], [Receiving Actor]]*[2], [Timing].

With the exception of 'create' and 'delete', each operation is equivalent to one or more requirements.

16.1Describing The Operations

Let’s start by describing the operations using ad hoc text, without any formal structure.

The operations for the first iteration of the Menu System, (as derived from the Serve Customer use case), are listed by class below.

Bill:

·         Display Bill - Displays the bill for the customer's order to the customer.

Category:

·         Display Category - Displays a selected category of menu items to the customer.

Customer:

·         Assign Customer To Table – Relates a customer to a table and indicates that the table is occupied to the head waiter.

·         Cancel Customer - Removes all customer selections from the system, resets the table display and indicates that the table is free to the head waiter.

Kitchen:

·         Deliver Order - Informs the head waiter that the customer order is ready for delivery.

·         Display Order - Displays a customer order to the kitchen.

Menu:

·         Display Menu Categories - Displays the menu categories to the customer.

MenuItem:

·         Display Menu Item - Displays the details of a selected menu item to the customer.

Order:

·         Display Confirm Order - Requests the customer to confirm that the displayed order is correct.

·         Unconfirm Order - Reforms the confirm order request and displays the menu categories to the customer.

·         Add To Order - Allows a customer to select a menu item and add it to their order.

·         Remove From Order - Allows a customer to select an menu item on their order and remove it from the order.

·         Display Order Total - A continuously updated display of the total cost of all items on a customer order.

Payment:

·         Accepting Payment - Allows the head waiter to select a table and display the bill for the customer.

·         Confirm Payment(add this to the class) - Allows the head waiter to inform the system that a customer payment has been accepted.

Receipt:

·         Display Receipt - Displays the receipt for a confirmed payment to the customer.

·         Print Receipt - Creates a paper copy of a displayed receipt.

Restaurant:

·         Display Table - Allows the head waiter to make a table available for customers.

·         Remove Table - Allows the head waiter to make a table unavailable to customers.

·         Display Restaurant Layout - Displays the available tables to the head waiter.

Table:

·         Request Assistance - Displays a request for assistance for a particular table, to the head waiter.

·         Display Instructions - Displays the system ordering instructions to a customer.

·         Cancel Assistance - Removes a previous request for assistance from the head waiter display.

·         Display Off - Shutsdown the customer interface for a particular table.

16.2Adding Detail To The Requirements

For each operation, identify the formalized parts of the requirement in terms of;

·         a unique identifier – because the operation name may not be unique, precede the name with a requirement number of the form ‘SR’#,

·         precondition – the state(s) that the system must be in before the requirement may execute,

·         trigger - the event that initiates the requirement execution,

·         initiator - the actor that initiates the requirement,

·         input - the data used by the requirement during execution,

·         output - the external responses of the system during execution of the requirement,

·         receiver - the actor(s) that the response is sent to,

·         timing - and the time to complete execution of the requirement.

Try to limit requirements to 1 event -> 1 response. If a single event stimulates several responses, it may be more efficient (for maintenance purposes and to reduce complexity) to break each response into a single requirement with the same event stimulus.

The operations in section 1.1, are assigned an Id and entered into the following table.

16.3Writing Out The Textual Requirements

Figure 1: shows the model operations broken into their constituent parts.

Table 1 : Table Of Requirement Parts

Using a MS Word table is not recommended, (I added this for readability), instead, the same information may be entered directly into a SharePoint table, as shown in Figure 1:.

                                                                                   Figure 1:    SharePoint Table Of SWRs

16.4Formalizing The Requirements As Text

Finally, we take each row of Table 1 : Table Of Requirement Parts, and write it out as formalized text using the following template[4]:

[Identifier] - When [Precondition], and [Initiating Actor] [Trigger, Input], the system [[Output], [Receiving Actor]]*, [Timing].

SWR1 -       Display Bill

When an order has been placed, and the kitchen enters the order is ready for a table, the system will display the order total (as order total cost + order tax), to that Customer table, after 120 seconds and within 300 seconds.

SWR2 -       Display Category

When the menu is displayed, and the customer selects a category, the system will display that category, (as defined in the restaurant database[5]), to the customer, within 3.

SWR3 -       Cancel Customer

When a table is occupied, and the head waiter, enters cancels customer for a table, the system will display the table as free, to the head waiter, within 3 Seconds.

SWR4 -       Assign Customer To Table

When a table is free, and the head waiter, assigns a customer to a table, the system will display the table as occupied, to the head waiter, within 3 Seconds.

SWR5 -        Deliver Order

When an order has been placed, and the kitchen indicates that the order is ready, for the table that placed the order, the order is displayed to the head waiter, within 3.

SWR6 -       Display Order\

When an order is displayed to a customer and the customer confirms the order, the order for that table will be displayed to the kitchen, within 3.

SWR7 -       Display Menu

When a table is occupied and the table customer selects the menu, the menu for the day (as defined in the restaurant database) will be displayed to the customer table, within 3.

SWR8 -       Display Menu Item

When a table is occupied, and the customer requests to display a menu item, the system will display the details of the selected menu item (as recorded in the restaurant database), the customer table, within 3.

SWR9 -       Display Confirm Order

When a table is occupied, and the customer requests to display their order, the system will display the customer’s order to the table with a request to confirm the order, within 3.

SWR10 -   Unconfirm Order

When a customer order is displayed with a confirmation notice, and the customer cancels, the system will display the system menu to the customer, within 3.

SWR11 -   Add To Order

When the menu is displayed, and the customer adds a menu item, the menu item will be added to the customer order displayed to the customer, within 3.

SWR12 -   Remove From Order

When an order is displayed to the customer, and the customer select an item to remove from the order, the system will display the customer order with the item removed to the customer, within 3.

SWR13 -   Display Order Total

When a table is occupied, and the customer selects an item to add or remove on the order the system will display the order total cost to the customer, within 3.

SWR14 -   Accepting Payment

When an order is ready, and the head waiter, requests to display the order for that table the system will display the order (including total cost) to the head waiter, within 3.

SWR15 -    Confirm Payment

When an order is ready, and the head waiter indicates that payment has been accepted for that table, the system will display a that payment has been made for that table to the head waiter, within 3.

SWR16 -   Display Receipt

When an order has been confirmed as paid by the head waiter, the system will display a  receipt for the order to the customer, within 3.

SWR17 -   Print Receipt,

When a receipt is displayed to a customer, and the customer requests to print the receipt, the system will send the receipt to the printer, within 3.

SWR18 -   Display Table

When a table is unavailable, and the head waiter, selects the table, the restaurant display will indicate that the table is available to the head waiter, within 3.

SWR19 -   Remove Table

When a table is available, and the head waiter, selects the table, the restaurant display will indicate that the table is unavailable to the head waiter, within 3.

SWR20 -   Display Restaurant Layout

When the system is operational, the head waiter is displayed the restaurant layout (including available tables), within.[6]

SWR21 -   Request Assistance

When a table is occupied and the customer at that table requests assistance, the system will inform head waiter of the table requesting assistance, within 3.

SWR22 -   Display Instructions

When the restaurant layout displayed and the head waiter indicates that a table is available, the system will display the menu instructions to that table, within 3.

SWR23 -   Cancel Assistance

When a table is requesting assistance, and the customer cancels assistance, the system will indicate that the table is no longer requesting assistance to the head waiter, within 3.

SWR24 -   Display Off

When the restaurant layout is displayed, and the head waiter indicates that a table is unavailable, the system will remove the display from that table, within 3.

Although it may be considered unnecessary, I that find that writing the SWRs out as lines of text, helps to find errors, and clarify the exact meaning of the requirements.

16.5Updating The Application Use Cases

The software requirements have been derived as a result of analyzing the Application Use Cases. We now verify that requirement information has been captured within a the AUC model. This is a manual process that involves:

For each use case step in the AUC model;

·         locate a SWR that corresponds to the requirements for that use case step

·         verify that information captured by the SWR is captured by the use case step and its supplementary requirements

·         indicate the captured information in the SWR table, as shown in Figure 2:

                                                                                            Figure 2:    SWR With Markup

(The SharePoint table has been exported to MS Excel, for editing purposes, since my version of SharePoint does not appear to support coloring of cells.)

·         A column identifying the AUC that captures the SWR has been added to the table.

·         Cells that are colored ‘green’ indicate that the SWR component has been captured by an AUC step.

·         Cells colored ‘orange’ indicate that the information needs inspection in the AUC model.

·         Cells not colored, have not yet been inspected.

·         once every AUC step has been inspected, the ‘orange’ cells need to be inspected in order to discover why the SWR is inconsistent with the AUC model.

·         only when all cells in the SWR table are colored ‘green’ can we declare

‘our use case model has been fully analyzed’.

16.6Summary

Process steps past detailing of the use cases, are concerned with formalizing requirements in order to check for consistency and completeness. Most projects will not feel the need to analyze their requirements to this extent, but if you do, the final result is a set of textual one sentence paragraphs that form a complete set of testable requirements.

These requirement statements were derived from an executable model of the system under construction. Ideally, it would be nice to be able to automatically derive these text statements from the model. Perhaps by running a script that parses every operation to extract the details of the operation. Maybe this will appear in a future edition of this work ..