Although the project vision gives us some idea about the business goal for the project, it does not yet address the scope. To achieve a detailed project agreement, we must create a high-level requirements specification that defines the scope of the project by listing functional and nonfunctional requirements. It should be emphasized that developing the high-level requirements specification often requires the involvement of many people with very different backgrounds, including business or customer representatives, managers, engineers, and salespersons.

During the course of this book the Unified Modeling Language (UML) is used for requirements gathering, requirements analysis, and software design. Altogether, UML defines 12 diagrams for modeling software systems. The diagrams are categorized in three groups, as shown in Table 4.1.

We will introduce several of the UML-defined diagrams, explaining them at the time they are first used. Class diagrams, package diagrams, sequence diagrams, and activity diagrams are introduced in this chapter and in Chapter 5. For more detailed information about UML, please see the references section.

A commonly used method to discover and break down high-level requirements in a well-understood language is the UML notion of use case diagrams. Figure 4.1 shows a high-level use case diagram for the Online Photo Shop project.

Figure 4.1. Use Case Diagram for Online Photo Shop

The symbols that look like people are actors. They represent outside persons or systems that interact with the system under development. For our project, there are two kinds of actors: the customer and the printing and embossing business. The use cases are visualized by ellipses and can be connected to other use cases to show their dependencies. The Online Photo Shop rectangle enclosing the use cases shows that these use cases are all part of the same system. It is also possible to create use case diagrams to visualize different systems by connecting two or more systems, showing their dependencies in the use case diagram.

The use case diagram in Figure 4.1 gives an overview of how the overall system will be used and of the external and internal interactions. Although this information is essential, it is not sufficient to capture all requirements. In our experience, use case diagrams are very useful to give a first overall look at a system and to better illustrate how it fits into its environment. However, use case diagrams are not the most efficient method for adding details to requirements or for describing nonfunctional requirements (constraints, performance, and so on). To add this information, it is usually sufficient to develop a well-structured text document containing the initial use case diagram plus a description of all requirements. This doesn't mean that the use case diagram becomes obsolete after the inception phase; on the contrary, it will be well maintained throughout the entire project. It is a good practice to add new use cases whenever you see added value in extending the initial use case diagram.

4.2.1 Requirement Keys

To better identify the various requirements during all project phases, we assign a unique identifier, called a key, to each requirement. These keys let us trace each requirement throughout the core workflows and phases of the Unified Process. To ease the tracing process, we recommend avoiding the use of spaces and capitalized letters in the identifier name. Another good practice is to include a type specification in the keys because you may apply various procedures, such as code reviews, test, and so on, to various categories of requirements. In the field of medical devices, for example, life critical or hazardous functionalities require higher-quality measurements than do nonhazardous functionalities. For the Online Photo Shop project we distinguish between the categories shown in Table 4.2.

4.2.2 Using XML for Requirements Documents

Traditionally, you create a requirements specification document or table of requirements using a spreadsheet or word processor such as Excel or Word, or a text editor such as Framemaker, Tex, or Latex. The latter three tools offer the big advantage of enforcing a structure on the document, letting the author focus on the content rather than the formatting. In addition, they create documents as simple text files, and that allows you to extract the requirement keys with little effort. However, these tools are not as easy to use and require training for the employees. Framemaker might be a good alternative for larger documents because the documents are edited using a WYSIWYG (what you see is what you get) view.

Framemaker also lets you save documents in plain XML format, which can be easily parsed. With the integration of the XML standard into new products such as C#, Visual Studio.NET, and Internet Explorer, we suggest the use of XML even for writing the requirements specification. For Microsoft Word, you must use a third-party tool (see, for example, www.logictran.com) to convert documents into XML format. This restriction will go away in Microsoft Word 2003.

We strongly encourage you to create the requirements document using a text editor and then export the document into XML format. Nevertheless, we show an example of how to create an XML requirements document without using any tool. In this way, you can learn the basics of XML and its use. The acquired knowledge will be useful when you try to trace the requirement keys through the stages of development in the transition phase.

Listing 4.1 shows a template requirements specification document defining one functional requirement key (F:image_crop) and a constraint (C:platform_os) for the target platform in the Online Photo Shop project. The requirement name consists of two parts in the XML file. The first part is the prefix, which identifies the category to which the requirement key belongs, as shown in Table 4.2. The second part is the actual name of the requirement. This approach lets us easily extract the category or requirement name when parsing the XML file with the help of a script, as shown later in the book.

Listing 4.1 RS.XML: XML Requirement Specification Template

Online Photo Shop 1.0 The editor should provide functionality to select a region of interest and crop an image to that region. img/crop_image.gif The target platform operating system is Windows XP Professional.

The structure of the document is fairly simple and easy to understand. XML requires each document to start with an tag identifying the version of the XML standard used and to enclose the document with tags. Inside the tag we use the keyword to begin a new system, and to start a list of requirements for this system. The structure of the document can be defined according to the particular project needs. We choose to add a and tag to the assembly and to add a

and optional tag for external references to each requirement.

The structure of XML is very clear, enabling easy addition of new requirements or even systems, but the readability of a plain XML document is not very good. This is where XSL stylesheets come into play. XSL stylesheets extract and format the requested data of an XML document in any desired way. Listing 4.2 shows an XSL stylesheet that transforms the XML requirement specification as shown in Listing 4.1 into an HTML file, which can be displayed using the Microsoft Internet Explorer Web browser. The XSL stylesheet shown in Listing 4.2 is provided with the sample solutions on the accompanying CD (RS.xsl). It can be customized and used as a template for other projects.

Listing 4.2 RS.XSL: XSL Requirement Specification Stylesheet

Requirement Specification

V

To associate the XML requirement specification document with this XSL stylesheet, we add the following line to the beginning of the XML document:

Now we can open RS.XML with the Web browser, which is now linked to the stylesheet, and we can view a nicely formatted document. The HTML page lists the requirement keys, their category, and a summary, as shown in Figure 4.2.

Figure 4.2. Requirement Specification Document in Internet Explorer

Don't be discouraged if you don't yet fully understand the stylesheet file. You create the XSL file only once for a project, and you can use the provided XSL template as a starting point for other projects. It is also very likely that a stylesheet that meets the needs of a particular project already exists, or it can easily be developed by someone with XML knowledge in the project team.

It is not necessary for all the team members involved in defining the requirements to have knowledge about XSL or HTML. The advantage of having the requirements defined in an XML text file is that it not only lets us create nicely formatted HTML pages but also lets us extract information from it easily. For example, you can extract all requirement keys into a simple text file or even into a scripting job (to trace them to the actual implementation code or to determine test coverage).

Because of these advantages, we describe all requirements for Online Photo Shop using the XML and XSL files. To include the use case diagram in the requirements specification, we save the use case model in GIF format and add the following two lines to the stylesheet, right after the

tag at the beginning of the file:

Use Case Diagram

If you now open RS.XML in Internet Explorer, you can see the UML use case diagram in the first subchapter, and the list of requirements of Online Photo Shop in the second.