Writing Functional Requirements to Support Use Cases

Writing functional requirements to support use cases

Background:
In our previous post, Sample use case examples, we created two informal use cases. The use cases were written to support product requirements defined as part of a project to reduce test suite maintenace costs. In this post, we will define functional requirements that support these use cases. This process is an example of using structured requirements, applied to a small real world project.

Reviewing the use cases

We previously defined the following two use cases (details in the previous post):

• Developer adds a new script and maps to existing inspections
• Developer adds a new inspection and maps to existing scripts

When we wrote Top ten use case mistakes one thing we highlighted was the importance of not incorporating design or implementation details into the use case. The same applies to writing functional requirements. We’ll keep that restriction in mind when writing our requirements.

The structure of the requirements looks like this:

For this post, we will pick the the second use case, ‘Developer adds a new inspection and maps to existing scripts’, and define the supporting functional requirements.

Writing the functional requirements

Here are the requirements we’ve written to support this use case.

1. The user can create mappings from a single new inspection to existing scripts. The user will associate scripts with the inspection that has just been added. The associations will represent mappings that cause the inspection to be evaluated against the script, resulting in tests. Each association between an inspection and a script represents a unique test. An inspection can be associated with any number of existing scripts. The inspection does not have to be associated with any scripts. If there are no associations associated with an inspection, it will not result in any tests.
2. The software will present script-associations to the user. The software will present feedback to the user that indicates the set of all existing scripts associated with a particular inspection.
3. The user will be able to identify similar existing scripts. The user will be able to search, filter, or otherwise identify a set of scripts that have common characteristics.
4. The user will be able to define automatic associations with future scripts. The user will be able to define a criteria that allows for scripts added in the future to be automatically associated with an existing inspection. The criteria will act to search, filter, or otherwise identify any future scripts as having common characteristics.
5. The software will automatically associate scripts with inspections. When a user identifies a set of criteria that can be used to identify existing or future scripts, the software will automatically associate those existing scripts with the inspection. If the inspection is so designated, it will automatically be associated with scripts created while that inspection is included in the test framework. The inspection will be associated only with those future scripts that meet the criteria for association.

Looking at what we’ve written

In the first requirement we’ve presented some detailed information about scripts, inspections and tests, but without describing implementation details. These objects have relationships that are business rules, not implementation guides. An object oriented implementation will likely create objects that have a very similar structure to these business rules. A database implementation would likely have an ER diagram that is also very similar. We could include a diagram that presents these business rules if we were using OOA/OOD techniques.

In the second requirement, we identify that the user will be given feedback by the application. With a tightly knit team of senior developers and product managers, you can make the case that documenting this requirement is busy-work. You could argue that the developers will obviously create software that provides feedback to it’s users. We feel that this is a small amount of incremental effort to document and manage this requirement, in return for the assurance that it will be implemented.

In the third requirement, we were very careful to not define any implementation criteria, such as using tags, or hierarchies, or inferring “similarity” from some characteristics of the scripts. We wanted to make sure that the designers have the latitude to create a solution of their design.

The fourth requirement introduces a new idea – minimize the cost of mapping scripts to test cases by automatically mapping the scripts to the test cases. This idea was created during a requirements elicitation session, and everyone agreed that it seemed to be very valuable. While this does define that the software must do something in particular, it does not specify how the software must accomplish it. There was an ideation process that resulted in the idea of automatic mapping, and as a product manager, I determined that it should be a requirement of the software that it support this functionality due to the reduction in effort that it would create for developers when using the test framework.

The fifth requirement works in conjunction with the third and fourth requirements. In those requirements, the user can specify criteria for script selection. The fifth requirement assures that the software will then create associations between the selected scripts and the inspection.

We validated that the functional requirements above would enable the selected use case, and verified with the development team that they were not ambiguous.

In summary

1. In this post we established the context (a real world project) in which we are writing requirements.
2. We then identified the use case for which we would write requirements, and wrote the requirements.
3. We reviewed the requirements that we wrote – highlighting some of the key thoughts about why we wrote them this way.
4. We validated the requirements both against the use case they supported, and with the developers who have to implement them.

The next step in the software development process is to provide a rough estimate of the cost of implementing this solution, so that we can evaluate the ROI of the solution. We can either wait for approval of the project based on the rough estimate of ROI, or we can move into a design phase that sketches out the high-level architecture of the solution in order to create a work breakdown structure and provide a more detailed estimate.

We believe that the rough ROI analysis is the right next step. That analysis would have one of three outcomes – obviously good investment decision, obviously bad investment decision, we need more details to make a decision.