Tool Mentor:  Capturing a Common Vocabulary Using Rational RequisitePro

Purpose

The purpose of defining a common vocabulary is to decrease ambiguity among team members and to establish a common language when you talk about the system you are building. You can use a common vocabulary in all textual descriptions of the system, especially in use-case descriptions.

Related Rational Unified Process™ information: 

• Activity: Capture a Common Vocabulary 
• Activity: Capture a Common Business Vocabulary.

Overview

A Glossary provides a definition for each term commonly used in the description of the system you are building. Each project should have one Glossary document.

Tool Steps

To document the project Glossary using Rational RequisitePro:

1. Add the Glossary document type to your project (if necessary)
2. Create a Glossary document
3. Create requirements in the Glossary document

1.  Add the Glossary document type to your project (if necessary) 

You can use the Glossary outline provided in Rational RequisitePro if the Glossary document type is available to your project. If your project was created using any of the three templates included with RequisitePro, the Glossary document type is already available; you can move to procedure 2.

To add the Glossary document type to an open RequisitePro project:

1. On the Tool Palette, click Project > Properties. The Project Properties dialog box appears.
2. Click the Document Types tab and click Add. The Document Type dialog box appears.
3. Type a name, description, and file extension for the document type. The file extension is applied to all documents associated with the document type. GLS is a commonly-used extension for glossary documents.
4. In the Default Requirement Type drop-down list, click Glossary Requirement type and go to Step 5. If Glossary Requirement type is not included in the drop-down list, click New. The Requirement Type dialog box appears.
   • Type "Glossary Requirement type" in the Name field.
   • Type "TERM" in the Prefix field.
   • Type or change the information in the other fields as desired.
   • Click OK to return to the Document Type dialog box.
5. In the Outline Name drop-down menu, select RUP Glossary (for software development) or RUP Business Glossary (for business modeling).
6. Click OK to close the Document Type dialog box.
7. Click OK to close the Project Properties dialog box.

For More Information

Refer to the following topic titled Creating and modifying document types (Index: document types > creating) in the RequisitePro online Help.

2. Create a Glossary document

The Glossary document contains terms and definitions identified during all activities of the project and especially when you are eliciting stakeholder needs. (See Activity: Elicit Stakeholder Requests.)

To create the Glossary document:

1. On the Tool Palette, click Document > New. The Document Properties dialog box appears.
2. In the Name field, type "Glossary" (this will be the way you refer to the Glossary document in RequisitePro).
3. In the Description field, type a short description.
4. In the Filename field, type a file name, which RequisitePro will use when saving the Glossary document to disk.
5. In the Document Type drop-down list, click Glossary Document type (for software development) or Business Glossary Document type (for business modeling).
6. Click OK to close the Document Properties dialog box. RequisitePro opens the newly created Glossary document in the Word Workplace (the RequisitePro Microsoft Word interface).
7. In the newly created Glossary document, add terms and their definitions. Consider using aliases for commonly used terms under the same definition (for example, Operator – see Machinist).
8. In the Word Workplace, click RequisitePro > Document > Save to save the Glossary document.

For More Information

Refer to the following topic titled Creating requirements documents (Index: documents>creating) in the RequisitePro online Help.

3. Create requirements in the Glossary document

The Glossary does not contain requirements per se; however, there may be times when 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 redefinition of terms in the Glossary, and you may have to update some documents to reflect that change. Marking such terms as requirements will allow you to set traceability links between Glossary terms and product features or systems requirements that you might want to reword after a Glossary term definition has been revisited and agreed upon.

To create requirements in the Glossary document:

1. Select (highlight) the text of the Glossary term.
2. In the Word Workplace, do one of the following:
   • Right-click and select Create Requirement.
   • Click RequisitePro > Requirement > Create.
   The Requirement Properties dialog box appears.
3. Accept the Glossary Requirement Type (TERM) as the requirement type, and click OK to close the Requirement Properties dialog box.
4. In the Word Workplace, click RequisitePro > Document > Save.

For More Information

Refer to the topic titled Creating requirements in a document (Index: requirements>creating in documents, results) in the RequisitePro online Help.

Copyright  © 1987 - 2001 Rational Software Corporation

Rational Unified Process