Guidelines: Important Decisions in Requirements

Topics

• Decide How to Use Artifacts
• Decide Which Reports to Use
• Identify Configuration Items
• Decide How to Maintain "Input Requirements"
• Decide How to Approve Use Cases

Decide How to Use Artifacts

Decide which artifacts to use and how to use each of them. The table below describes which artifacts are mandatory, and which need only be used in some cases. The "tailoring comments" give some guidelines as to how you can tailor each artifact.

For a complete description of each artifact, see Requirements Artifacts. For each artifact read the section "Tailoring" where the advantages and disadvantages of that specific artifact are discussed.

Tailor each artifact by performing the steps described in "Tailor Artifacts per Workflow" in the Activity: Develop Development Case.

Decide Which Reports to Use

Decide which reports to use by deciding:

• Which work reports to use.
• Which reports should be used for final documentation.

As a starting point use the following reports:

• Report: Use-Case
• Report: Use-Case Model Survey
• Report: Use-Case Storyboard
• Report: Actor
• Report: Class

These are described in more detail starting from the Report Overview.

Which "Work" Reports to Use

Decide which reports to use as temporary work reports from which to extract information from the use-case model, to make reviewing easier.

It is recommended you use Use-Case Report, and Use-Case Model Survey as "work" reports. For a large use-case model, it might be a good idea to introduce a new report, Use-Case Package Report, which describes a use-case package, and all its contained use cases.

Which Reports to Use for Final Documentation

Decide which, if any, reports you want to capture the final results of the Requirements workflow.

At the end of the project you store the results in a configuration management tool. However, your organization may require that the results are captured on paper. If that is the case, you must decide which reports to use to capture the entire use-case model.

If the predefined reports do not suit your needs, tailor the outline of these reports, or create new ones. For each report decide how the report should be used: "To be skipped", "Casual", "Informal", "Formal-Internal", or "Formal-External". For more details, see, Activity: Develop Development Case.

Here are some examples of different ways to capture the entire use-case model.

1. One report for each use case (Use-Case Report). This is usually the choice if you want to approve each use case in formal reviews ("Formal-External"). In addition to this report there must be one report that is a survey of the use-case model (Use-Case Model Survey). These two reports together, capture the entire use-case model.
2. Create a new report that captures the entire use-case model, and recursively all its contents, including the details of each use case. This becomes one very large document, that will then be treated as "Formal-Internal", or "Formal-External".
3. Create a new report that completely captures a use-case package and all its enclosed use cases; a Use-Case Package Report. In addition to this report there must a survey of the use-case model (a Use-Case Model Survey). These reports together will capture the entire use-case model and its contents. They will be treated as "Formal-Internal", or "Formal-External".

Identify Configuration Items

Read about the artifacts in Requirements Artifacts, then decide which of the artifacts should be handled as separate configuration items.

If you decide to not handle an artifact as a separate configuration item, then it is recommended that it be part of the enclosing artifact. For example, if you decide to not handle each use-case package as a separate configuration item; then the use-case packages should be part of the same configuration item as the use-case model.

It is up to each individual project to decide what needs to be handled as separate configuration items. When you develop a system incrementally, make sure that you create a baseline at the end of each iteration. In this way, you can control the difference, iteration to iteration.

It is recommended that you clearly separate, in your configuration items, Requirements artifacts from the artifacts of Analysis & Design or Test. For example, do not put use cases, and the corresponding use-case realizations, in the same configuration item, because they are likely to be updated on different occasions.

It is recommended that all the properties of an artifact be part of the same configuration item as the artifact itself. This means that if a property of an artifact is stored in a separate file from the artifact itself, then these files should be part of the same configuration item.

For example, assume that a use case is stored in a file of a modeling tool, and its property "Flow of events" is stored in an external file. Then the version of the use case in the modeling tool, and the version of the external file should be controlled together.

Decide How to Maintain "Input Requirements"

This section only applies if a more or less formal contract, standard or specification document is imposing requirements to the requirements effort; below this is called the "input requirement specification".

During the requirements effort you capture the requirements in a Vision document, in a Stakeholder Needs document, in a use-case model, and in Supplementary Specifications.

You need to decide whether the "input requirements specification" should be maintained or not. Should you go back and update the input requirements specification when you discover a requirement was bad, wrong, or faulty? You must also decide how traces or references between the "input requirement specification" and the use cases, should be maintained.

Choose one or a combination of the following strategies:

1. Do not update the "input requirement specification". Let the use cases and the Supplementary Specification, specify what the system should do hereafter.
2. Do not update the "input requirement specification", but maintain the traceability from use cases back to the "input requirement specification".
3. Update the "input requirement specification" with all the work and cost involved.
4. Let the "input requirement specification" evolve into a Supplementary Specification, containing non-functional requirements. The functional input requirements are simply transferred to the use cases.

Most project find that the number of requirements that are bad, faulty or wrong is so large that it does not make sense to maintain the original "input requirement specification". A very small number of projects have a customer that is willing to pay for the work of updating the "input requirement specification" with the new information revealed during use-case modeling.

Don't stress this question too early. In the beginning of the project people still believe in the initial requirement specification, but after working through the problem area with use case, most people have quite a different view of the initial requirement specification.

Decide How to Approve Use Cases

Decide how to approve the use cases. A lot of time can be saved by limiting the number of use cases that have to be formally reviewed by the customer. Maybe it is acceptable for the customer to review and formally review a subset of all use cases.

Choose one or a combination of the following strategies:

1. All use cases have to pass formal external reviews with users representatives external to the project.
2. Some secondary use cases can be approved in a simplified way; informal or an internal formal review.

Secondary use cases are those use cases that are essential to the system, but not to the task of the primary user. For example, use cases related to the administration and maintenance of the system: adding users to the system, changing their authority, and taking backup. The system will not work without these use cases, but they are not of primary interest for the important users.

Which strategy you use depends on your relationship with your customer; do they trust that you can do the supporting use cases correctly without a formal approval process? This saves a considerable amount of time, but will you reach the right quality of the use-case model?

Notice that a solution to the "problem" may be to involve the customer in the Requirements effort. By involving customer representatives, they will be able to approve, or give recommendations to other customers. And by involving the customer, the project gains credibility.