Tool Mentor: Using RequisitePro to Capture a Common Vocabulary

Purpose

The purpose of defining a common vocabulary is to decrease ambiguity among team members and to expose a common language when talking about the system to build. A common vocabulary can be used in all textual descriptions of the system, especially in use-case descriptions.

Related Rational Unified Process Activities:

• Capture a Common Vocabulary (of the system analyst),
• Capture a Common Vocabulary (of the business-process analyst).

Overview

This Tool Mentor is applicable when running Microsoft Windows 95/NT 4.0.

A Glossary provides a definition for each term commonly used in the description of the system to build. There is one Glossary document per project.

To document the project Glossary using RequisitePro:

1. Create a Glossary document.
2. Complete the Glossary document.
3. (Optional) Mark requirements in the Glossary document.

1.   Create a Glossary Document

The Glossary document will contain terms and definitions discovered during all activities of the project, especially Elicit Stakeholder Needs.

• From the RequisitePro’s Tool Palette, select Document=>New. The Document dialog comes up.
• Fill out the parameters as shown on the picture.
• In the Name field, enter "Glossary" (this will be the way you refer to the Glossary document in RequisitePro).
• In the Description field, enter a short description.
• In the Filename field, enter a filename (RequisitePro will use this filename when saving the Glossary document to disk).
• Select the "Glossary" outline as the Document Type. The template for this document type organizes the Glossary information into Term and Definition sections.
• RequisitePro will open the newly created Glossary document in its Word workplace.

2.   Complete the Glossary Document

• In the newly created Glossary document, for each term to define, add the term name and its respective definition. Consider using aliases for commonly used terms under the same definition (ex: Operator – see Machinist). We recommend using italic to refer to terms already defined in the Glossary.
• Save the Glossary document by selecting Document=>Save on the RequisitePro’s Tool Palette.

3.   (Optional) Mark Requirements in the Glossary Document

The Glossary does not contain requirements per se. However there might be times where some Glossary terms could be used as names for classes, especially Entity Classes. See Class Design. By marking these terms as requirements, you can automatically create classes of that name in Rational Rose, using the Rational Synchronizer.

You may also want to keep track of the fact that terms have been redefined in the Glossary, and some documents need to be updated to reflect that change. Marking such terms as requirements will allow you to later set traceability links between Glossary terms and product features or systems requirements that might need to be reworded after a Glossary term definition has been revisited and agreed upon.

• From the RequisitePro Word workplace, for each glossary term outlined in the Glossary document, select the text and click on the Tool Palette Create Requirement from highlighted text icon. The Requirement dialog is displayed.

• In the Requirement dialog, select TERM as the requirement type.
• Click OK to dismiss the Requirement dialog.
• Repeat the two steps above for each Glossary term.
• When done, save your Glossary by selecting Document=>Save on the RequisitePro’s Tool Palette. This will create requirements in the RequisitePro project. These requirements will then be available to automatically create Classes in Rational Roseä via the Rational Synchronizer.