Sybase Technical Library - Product Manuals Home
[Search Forms] [Previous Section with Hits] [Next Section with Hits] [Clear Search] Expand Search

Chapter 4:  Working with a requirements model [Table of Contents] Chapter 6:  Requirements Model Glossary

Requirements Model User's Guide

[-] Chapter 5: Using MS Word with a requirements model

Chapter 5

Using MS Word with a requirements model

About this chapter

This chapter explains how you can work jointly with an MS Word document and a requirements model.

Case 1

You can start from an MS Word document...

raster

... and create a requirements model.

raster

The MS Word document and the requirements model can be linked.

Case 2

You can start from a requirements model...

raster

... and create an MS Word document.

raster

The requirements model and the MS Word document are linked.

Check-list

Before starting to work on the Requirements Model and MS Word, you must check the following list:

Creating a requirements model from an MS Word document

You can create a requirements model from an MS Word document using PowerDesigner (See Import feature) or MS Word (See Requirements menu and toolbar). The MS Word option is more direct.

Heading styles

To be properly converted into a requirements model, an MS Word document must use MS Word-based heading styles.

Graphics are not imported in a requirements model.

Importing an MS Word document as a requirements model

In PowerDesigner, you can call the Import feature in different ways:

The following procedure assumes you have an MS Word document available, with MS Word-based headings.

To import an MS Word document using the File menu:

In the PowerDesigner menu bar, select File-->Import-->Word Document.

The Open dialog box appears.

Select a directory in the Look in dropdown listbox, and an MS Word file (.doc) in the list.

Click Open.

The following message appears in the PowerDesigner window.

raster

Click Yes, if you want the MS Word document to be linked to the requirements model, so as you can synchronize them later on. The Save As dialog box appears. Select a directory in the Save in box, type a name in the File name box, and click Save.

or

Click No, if you do not want the MS Word document to be linked to the requirements model.

A message appears indicating that the MS Word document is being parsed to extract its paragraph titles. You can cancel the parsing at any time, only the parsed sections are converted into requirements.

When the parsing is over, the Select Titles to Import dialog box appears.

raster

Click the Expand All tool to display all titles.

raster

All titles are selected by default.

You can click the Deselect All tool, and then select the titles you want to convert as requirements.

Click OK.

The MS Word document appears in the workspace as a requirements model.

raster

The Files folder in the Browser tree view contains the file of the linked MS Word document.

Using MS Word to create a requirements model

An MS Word document can contain one or several titles, with their associated text, that you would like to use as requirements.

Check that MS Word has a Requirements menu...

raster

... and a Requirements toolbar.

raster

If not, select Tools-->Templates and Add-Ins, and check the WordToRqm.dot item.

The following procedure assumes you have an MS Word document open, with MS Word-based headings.

To use MS Word to create a requirements model:

In the MS Word menu bar, select Requirements-->Create/Update a Requirements Model from the Document.

or

In the Requirements toolbar, click the Create/Update a Requirements Model from the Document tool.

raster

The following message appears.

raster

Click Yes, if you want the MS Word document to be linked to the requirements model, so as you can synchronize them later on. The Save As dialog box appears. Select a directory in the Save in box, type a name in the File name box, and click Save.

or

Click No, if you do not want the MS Word document to be linked to the requirements model.

A message appears indicating that the MS Word document is being parsed to extract its paragraph titles. You can cancel the parsing at any time, only the parsed sections are converted into requirements.

When the parsing is over, the Select Titles to Import dialog box appears.

raster

Click the Expand All tool to display all titles.

raster

All titles are selected by default.

You can click the Deselect All tool, and then select the titles you want to convert as requirements.

Click OK.

The selected titles appear as requirements, with their description, in a new requirements model.

raster

The Files folder in the Browser tree view contains the file of the linked MS Word document.

How are a model and a document linked?

An MS Word document and a requirements model (or package) are linked when you need to synchronize them when they change.

The following sections explain how a document and a model (or package) are linked.

How is an MS Word document linked?

An MS Word document is linked to a requirements model (or package) through custom properties and requirement tags.

Custom properties

An MS Word document is linked to a requirements model (or package) through the Custom page of its property sheet.

To display the document property sheet, select File-->Properties.

raster

The Custom page displays information concerning the linked requirements model (or package):

Requirement tags

An MS Word document is linked to a requirements model (or package) when its sections (titles followed by a text) are bounded by a requirement start tag [PDRQM] and a requirement end tag [/PDRQM].

raster

To display the requirement tags, click the Show/Hide tool.

rasterHow is a requirements model linked?

A requirements model (or package) is linked to an MS Word document through an attached file and traceability links.

Attached file

A requirements model (or package) is linked to an MS Word document when the MS Word file appears in the Browser, in a Files folder attached to the model (or package).

raster

Packages

When a requirements model contains packages, each package can be linked to a specific MS Word document. A package cannot be linked to more than one document.

If the model is itself linked to a document, only the requirements which do not belong to a package are linked to the document.

For example:

raster

Note: The Files folder of the model item contains the model file and a shortcut for each package file.

Traceability links

A requirements model (or package) is linked to an MS Word document when the Traceability Links page of the model (or package) and each requirement property sheet displays the document file with Main document as Link Type and a bookmark for each requirement.

Example of a requirement property sheet:

raster

Creating a requirement from a selected text

In MS Word, the Create a Requirement from the Selected Text feature is useful in the following cases:

The following procedure assumes you have an MS Word document open, with MS Word-based headings.

PowerDesigner can be open, with an existing requirements model linked or not.

To create a requirement from a selected text:

In the MS Word document, select the section (title and text) you want to convert into a requirement.

raster

In the MS Word menu bar, select Requirements-->Create a Requirement from the Selected Text.

or

In the Requirements toolbar, click the Create a Requirement from the Selected Text tool.

raster

If the document is linked to a model, the section is directly exported as a requirement in the model. The location of the section, between a requirement end tag and a requirement start tag, determines the location of the requirement in the model. If the section has no title, then it is exported as a sub-requirement of the previous requirement.

If the document is not linked to a model, the following message appears.

raster

Click Yes, if you want the section to be linked to the requirements model.

or

Click No, if you do not want the section to be linked to the requirements model.

A Select the requirements model dialog box appears.

Select <New model>.

or

Select an existing requirements model. (It must be open in the workspace)

raster

Note: Only models open and not linked to a document, or containing at least one package not linked, appear in this dialog box.

Click OK.

If you selected <New model>, the Save As dialog box appears to let you save the new model. Select a directory in the Save in dropdown listbox, type a name in the File name box, select Word Document (*.doc) in the Save as type dropdown listbox, and click Save. A new requirements model appears with an atomic requirement corresponding to the selected text.

If you selected an existing requirements model, the Select a Place in Document dialog box appears with the model root node.

raster

Expand the model root node to reveal the requirements hierarchy, and select the location where you want to create the requirement.

raster

Note: Only packages that are not linked to a document appear in the dialog box.

Click OK.

The new requirement ("User list"), corresponding to the selected text, appears in the existing requirements model.

raster

Creating an MS Word document from a requirements model

In a requirements document view, you can write the title and description of requirements using the rich edit text features. To improve the layout and readability of a requirements model, you can transform it into an MS Word document.

You can also create an MS Word document from a package containing at least one requirement.

The following procedure assumes you have a requirements model open in the workspace. MS Word can be open or closed.

To create an MS Word document from a requirements model:

In the Browser tree view, right-click the model name and select Export as Word Document in the contextual menu.

or

In the menu bar, select Tools-->Export as Word Document.

If the requirements model has not been saved yet, the Save As dialog box appears. Select a directory in the Save in dropdown listbox, type a name in the File name box, select Requirements Model (xml) (*.rqm) in the Save as type dropdown listbox, and click Save.

The New dialog box appears.

raster

In the General page, select Blank Document and Document in the Create New box.

or

Select a template icon (.dot) and Document in the Create New box. You might want to use a template for predefined heading styles based on MS Word heading styles.

Click OK.

MS Word opens with a blank document, and the Save As dialog box appears.

Select a directory in the Save in dropdown listbox, type a name in the File name box, and select Word Document (*.doc) in the Save as type dropdown listbox.

Click Save.

The requirements appear progressively in the MS Word document. Only full descriptions (titles and descriptions) are exported.

Extract of an MS Word document created from a requirements model:

raster

The requirements model and the MS Word document are automatically linked. The document sections (titles and texts) appear between requirement tags ([PDRQM]...[/PDRQM]), and the MS Word file is attached to the model in the Browser:

raster

Note: If you export a package, the MS Word file is attached to the package in the Browser.

Inserting a requirements model into an existing MS Word document

A requirements model being a descriptive list of requirements, you might want to insert it into an existing MS Word document, e.g. a functional or technical specification.

A package containing at least one requirement can also be inserted into a document.

The following procedure assumes you have a requirements model open in the workspace and not linked to an existing document. MS Word can be open or closed.

To insert a requirements model into an existing MS Word document:

In the Browser tree view, right-click the model name and select Merge with an Existing Word Document in the contextual menu.

or

In the menu bar, select Tools-->Merge with an Existing Word Document.

If MS Word is already open, you might need to click its button which blinks in the taskbar.

The Open dialog box appears.

Select a directory in the Look in dropdown listbox, and an MS Word file (.doc) in the list.

Click Open.

The MS Word document is parsed.

When the parsing is over, the Select a Place in Document dialog box appears in the PowerDesigner window.

raster

Expand the Entry points node and all its sub-nodes, and select a title beneath which the requirements will be added.

raster

Click OK.

The MS Word file appears in the Browser, in a Files folder within the model item. The requirements model is now linked to the MS Word document.

raster

Double-click the MS Word file in the Browser tree view.

The MS Word document appears with the added requirements.

raster

The Merge feature is no more available in the contextual menu of the model item.

If you insert a package into an existing document, the MS Word file is attached to the package.

Updating an MS Word document from a requirements model

Once you have linked an MS Word document to a requirements model, you can change the requirements model and update the linked MS Word document.

The Update feature is available from the Browser:

Graphics

If you add graphics to a linked MS Word document, do not try to update the document from the requirements model, you will lose the graphics. Modify the document and then update the model from the document.

The following procedure assumes you have a requirements model open in the workspace and linked to an MS Word document.

To update an MS Word document from a requirements model:

Change the requirements model.

For example, add a requirement ("Provisional Budget").

raster

In the Browser tree view, right-click the model name, and select Update Word Document in the contextual menu.

MS Word is launched and the document is parsed and updated.

raster

Updating a requirements model from an MS Word document

Once you have linked a requirements model to an MS Word document, you can change the MS Word document and update the requirements model.

If you add graphics to a linked document, they will be preserved during an update of the model from the document.

The following procedure assumes you have an MS Word document open and linked to a requirements model.

To update a requirements model from an MS Word document:

Make changes in the linked MS Word document.

For example:

In the MS Word menu bar, select Requirements-->Create/Update a Requirements Model from the Document.

or

In the Requirements toolbar, click the Create/Update a Requirements Model from the Document tool.

raster

The Select Titles to Import dialog box appears.

Click the Expand All tool to display all titles.

raster

The titles already linked to a requirement have their check box selected and grayed. You cannot deselect them.

The added title ("Scenario options") is selected but not grayed.

Click OK.

The Merge Models dialog box appears.

raster

The new model, corresponding to the modified MS Word document, appears in the left panel. The existing model to update appears in the right panel.

Expand the Requirements folder, and select the deleted title ("User list") in the model to update.

Deleted titles are not selected by default in the models to update.

raster

The title with an added text line ("Scenario Descriptions") and the additional title ("Scenario options") are selected by default in the model to update.

Click OK.

The existing requirements model is updated with the recent changes.

raster

Detaching an MS Word document from a requirements model

You can always detach an MS Word document that is linked to a requirements model.

An MS Word document is linked to a requirements model when its sections (titles followed by a text) are bounded by a requirement start tag [PDRQM] and a requirement end tag [/PDRQM].

Extract of a linked document:

raster

In the MS Word menu bar, select Requirements-->Detach the Document from the Requirements Model.

or

In the Requirements toolbar, select the Detach the Document from the Requirements Model tool.

raster

The requirement tags disappear from the MS Word document.

raster

Detaching a requirements model from an MS Word document

You can always detach a requirements model that is linked to an MS Word document.

A requirements model is linked to an MS Word document when the MS Word file appears in a Files folder beneath the model item in the Browser...

raster

... and when the Traceability Links page of the requirements property sheet displays the MS Word file as a linked object of Main document type:

raster

To detach the model from the document, delete the document file in the Browser...

raster

... and the file will disappear from the Traceability Links page of the requirements property sheet:

raster
Chapter 4:  Working with a requirements model [Table of Contents] Chapter 6:  Requirements Model Glossary