Manage development of document-based requirements in parallel with IBM Rational RequisitePro

Ways to work with requirements such as use case specifications in Microsoft Word document format

IBM Rational RequisitePro was designed to support a serialized approach to requirements engineering. Due to shortened development cycles and multiple-team approaches, there is a demand for working on requirements in parallel. This article gives pointers on how to achieve that.

Joerg Moeller (joergmo@de.ibm.com), Advisory Accredited IT Specialist, IBM Corporation

Joerg has 10 years of experience in professional software development. As a member of the Rational Software Services team, he helps customers integrate Rational products with their software processes and customize them for their customer needs.



18 February 2010

Also available in Chinese Spanish

What you need to know first

This article focuses on document-based requirements, such as use case specifications. Database-based requirements might need different strategies for development in parallel.

The IBM® Rational® RequisitePro® documents must be stored in Microsoft® Word® format (not in Rational RequisitePro format), and the contained requirements must not have hierarchical (parent-child) relationships.

The scenarios described here have been tested with Rational RequisitePro Version 7.1.0 and Microsoft Office 2003, running on Microsoft® Windows® XP, Service Pack 2. To get familiar with the basic ideas and techniques, it is best to set up a test environment, because some of the actions could irreversibly damage data if they are performed incorrectly.

Basics

Rational RequisitePro has no branching or merging mechanism as IBM® Rational® ClearCase® does, for example. Storing RequisitePro documents in ClearCase to benefit from its branching and merging capabilities would not resolve the problem, because the ClearCase-Microsoft Word merge manager does not consider the embedded requirements that are stored in the RequisitePro database.

The only solution is to use native Rational RequisitePro functionality and to create separate instances of RequisitePro documents and requirements. With these separated instances, teams can work independently and then bring together the changes afterward. Additional requirement attributes can help in managing where a requirement was branched off from and where it was merged to. A trace relationship between the original requirement and the branch requirement can help you stay in touch with changes that are made to requirements by other teams.

Microsoft Word includes compare and merge functionality for documents and can be used for merging different versions of a document.


Configure RequisitePro

For Microsoft Word, it makes no difference if the document extension is different from .doc (such as .ucs for use case specification, for example). However, Word does not work with the Rational RequisitePro format for storing documents, so this has to be switched off.

  1. From the RequisitePro menu, click File > Project Administration > Properties.
  2. From the Project Properties window, select the Documents tab, and remove the check from the "Save documents in RequisitePro Format" check box (see Figure 1. Changing RequisitePro document format).
Figure 1. Changing RequisitePro document format
Documents tab of Project Properties

To increase the support of Rational RequisitePro for branch or merge scenarios, add two additional attributes to every requirement type that will be affected by branch or merge action.

  1. From the RequisitePro menu, select File > Project Administration > Properties.
  2. From the Project Properties window, select the Attributes tab, and add two additional text attributes named originates from and merged to (see Figure 2. Add supporting attributes to affected requirement types). They will hold the information about which requirement the requirement was branched off from and which requirement it has been merged with.
  3. Apply a default value, for example a hyphen (-), to make the attributes display that they are currently holding no value.
Figure 2. Add supporting attributes to affected requirement types
Requirement type and attribute options

Projects with parallel development are usually organized according to teams or releases. The project’s organization should be reflected in an appropriate package structure in RequisitePro. In this example, we’ll organize the project by releases, R10 and R11, as Figure 3. Reflect the project organization in the package structure).

Figure 3. Reflect the project organization in the package structure
Shows structure of the R11 use case

Branch a Rational RequisitePro document

To keep this example, simple there is only one use case specification in the R10 release package. An R11 branch will be branched off from the R10 release (modifying Use case requirements for the upcoming 1.1 release of a product). The use case specification contains only two requirements (see Figure 4. Starting situation in RequisitePro database and Figure 5. Starting situation in a RequisitePro document):

  • UC1: Withdraw cash
  • UC2: There is an active…
Figure 4. Starting situation in RequisitePro database
Use case to be branched into the R10 package
Figure 5. Starting situation in a RequisitePro document
Specification of the use case to be branched

To branch the existing Rational RequisitePro document to the R11 release:

  1. Open the R10 RequisitePro document, and, from the Microsoft Word menu, select RequisitePro > Document > Save As, and store the document in native Microsoft Word format.
  2. From the RequisitePro menu choose File > Import.
  3. In the Import Wizard dialog box (Figure 6. Branching – Import document), select Microsoft Word document and then browse to the previously stored file and click Next.
Figure 6. Branching – Import document 1, Withdraw Cash R10.DOC
Select source of imported requirements screen
  1. For the content to be imported, select Document only (Figure 7. Branching – Import document 2) and then click Next.
Figure 7. Branching – Import document 2
For Select Import Content: Document only
  1. Provide a meaningful name for the new Rational RequisitePro document. A good approach is to add the release tag to the name.

Note:Names for RequisitePro documents must be unique within each project.

  1. Select the appropriate document type (use case specification in this case), and click OK (see Figure 8. Branching – Import document 3).
Figure 8. Branching – Import document 3
Document Properties sections view
  1. In the Create Document window, select Yes.
  2. The bookmarks in the imported document are needed for identification of the included requirements, so select No in answer to "Do you want to remove these bookmarks?" because you need to keep bookmarks of embedded requirements (Figure 9. Branching – Import document 4).
Figure 9. Branching – Import document 4
Import Wizard dialog box
  1. Finally, select the Commit button (Figure 10. Branching – Import document 5).
Figure 10. Branching – Import document 5
Import Wizard screen with the Commit button

After the document has been imported, there is an exact copy of the original Rational RequisitePro document (including tagged requirements as shown in Figure 11. Branching – Branched document and requirements), and the R11 release package contains its own RequisitePro document (see Figure 12. Branching: R11 branch of R10).

Figure 11. Branching – Branched document and requirements
Specification of branched use case
Figure 12. Branching: R11 branch of R10
Branched use case in the R11 package

Notice that , during the import of the document, new requirements have been created. The newly created requirements are not copies of the original requirements but new instances with applied default values. Check whether the original requirements have attribute values that need to be entered for the copies of the requirements also.

The R11 release package now contains a separate requirements document together with its requirements. They can be edited entirely separately from the original requirement document and requirements.


Track the original and branched versions

In this simple example, it is easy to track the original and branch requirements. In real life projects with hundreds or thousands of requirements, you need a tool to help with oversight.

One mechanism that can be used is to establish a trace relationship between the original and the branch requirement (Figure 13. Tracking original and branch requirement by trace relationship). This serves two purposes:

  • Documentation is established for what the origin of the branch requirement is (the direction of the trace relationship could be from the original to the branch requirement).
  • A mechanism is established for notifying team members if changes to the requirements are made on a different branch (in case of complex use cases, it is good to keep in touch with the other teams).

A small limitation is that a trace relationship is not allowed to be circular. Therefore, you are limited to documenting either a branch or a merge relationship.

Figure 13. Tracking original and branch requirement by trace relationship
Shows R11 use case branch traced to the original

An alternative mechanism is to use additional attributes for managing branching or merging. You can document the status of the requirement by adding a text attributes to the concerned requirement types that say "originates from" and "merged to." No entry in originates from means that it is an original requirement. No entry in merged to means that the branch requirement hasn’t been merged yet (seeFigure 14. Using attributes for managing branch/merge).

Figure 14. Using attributes for managing branch/merge
Screen: tracking origin and source by attributes

Merge a RequisitePro document

If an existing document was branched, it is usually changed in some way. The change could be a modification, addition, or deletion. We’ll show you how to perform these three changes on our branched requirement document and work through the merge process so that you can see how they can be incorporated in the original requirements document later on. Here, there’s a modification in the use case title: the requirement UC4 has been removed and the requirement UC5 has been added (Figure 15. Modification on branched requirements document)

Figure 15. Modification on branched requirements document
Screen segment shows modification

After the modifications have been applied from the Microsoft Word menu, we select RequisitePro > Document Save to submit the changes to the database.

Now, merge these changes into the original requirements document. First, you need to create a temporary document.

  1. From the Microsoft Word menu. choose RequisitePro > Document Save As, and store the document in native Microsoft Word format.
  2. Open the temporary document and, from the Word menu, select Insert > Bookmark.

Navigate through the bookmarks by double-clicking them. Even though there is no RequisitePro document, specifically, there’s still one bookmark for each requirement in the requirements document. In this requirement document example, we have two bookmarks. One bookmark is for the modified requirement (Figure 16. Bookmark for modified requirement). The other is for the added requirement (Figure 17. Bookmark for added requirement).

  1. Remove any bookmark that is related to the modified requirements, because you don’t want RequisitePro to consider them during the import. The result should look like Figure 18. Cleaned bookmarks.
  2. Save the document when you are finished.
Figure 16. Bookmark for modified requirement
Bookmark named REQRY9EC1 selected, REQRYGOP1 not
Figure 17. Bookmark for added requirement
Bookmark window, REQRYGOP1 selected
Figure 18. Cleaned bookmarks
Bookmark window, only REQRYGOP1 remains

You can merge the modified temporary document into the original document.

  1. To retrieve the location of the original document, right-click the document and select Properties.
  2. Next, in the Document Properties window, select the General tab.
  3. You can copy the location of the document from the Directory field (see Figure 19. Document properties).
Figure 19. Document properties view
Directory field shows path to document
  1. From the temporary document, from the Microsoft Word menu, choose Tools > Compare and Merge documents.
  2. In the next window, browse to the original document (Withdraw Cash R10.ucs).

The difference can be resolved by accepting or rejecting the changes. Basically, there are three different scenarios to consider (Figure 20. Merging the original and branched document)

Scenario 1: Modifications to an existing requirement

The requirement is present in both the original and the branched requirement document. You want to get the changes made to the branched requirement into the original requirement. To do so, the original bookmarks must remain in the original document. When resolving the differences, reject any changes that refer to format changes or additions or deletions of use cases. Just accept the modifications being made on the text within the bookmark (if you want to get the changes back into the original; if not, reject them also.)

Scenario 2: Removal of requirements

The requirement is present in the original document but was removed in the branched-off document. If you want to remove the requirement in the original document, accept all changes related to this section. If that is not what you want, reject them completely.

Scenario 3: Addition of requirements

The requirement is not present in the original document, and it was added in the branched-off document. If you want to add the requirement in the original document, accept all changes related to this section. If you do not want to do that, reject them completely.

Figure 20. Merging the original and branched document
Use case steps in Word, Preconditions modified

For the sake of this example, we want to bring the modification, the deletion, and the addition to the original document. Therefore, after accepting and rejecting the changes as described, the final, merged result should look like Figure 21. Merge result in.

  1. Save the original file when you are finished.

Important:
Rational RequisitePro is not involved in the merge process, so it cannot recognize the changes until you open the original document from RequisitePro.

Figure 21. Merge result in Microsoft Word
Use case specification after merging
  1. Open the original file from the RequisitePro client. RequisitePro will detect the changes made to the document by the Microsoft Word merge process (Figure 22. RequisitePro detects changes from outside).
Figure 22. RequisitePro detects changes from outside
RequisitePro Document Changed alert with options
  1. Click Yes to update the database in accordance with the modified original file.
  2. Provide a meaningful description at the prompt (Figure 23. RequisitePro request a change description).
Figure 23. RequisitePro request a change description
Example: Merged from R11

During the update process, RequisitePro detected that one of the bookmarks belongs to a requirement located in the branched document. RequisitePro requires a unique location for any given requirement, so it gives you the choice to either cut and paste the requirement from the other document or create a copy, instead. Bear in mind that this is a complete copy of the requirement text and the attribute values.

For this example, create a copy to avoid pulling the requirement from the R11 release (Figure 24. Requirement Found view and options within RequisitePro ).

Figure 24. Requirement Found view and options within RequisitePro
'Copy the original requirement' selected

The final merge result in the R10 requirements document will look like Figure 25. Merge result in Rational RequisitePro.

Note:
If there are modified requirements, the attribute values will not be automatically copied as they were for added requirements. Instead, the attribute values need to be examined and aligned manually. As a last step, update the branched requirement attributes to reflect the fact that a merge was performed (Figure 26. Merge state displayed by attributes).

A clever combination of views, filtering on suspect links (changes have happened) and attributes (merge was not performed yet), could provide insight into which requirements are different and have to be merged.

Figure 25. Merge result in Rational RequisitePro
Original use case specification after merge
Figure 26. Merge state displayed by attributes
Attribute shows that branch use case was merged

Summary

Working in parallel on document-based requirements seems to add more flexibility to projects. But working in parallel also always means additional effort when it comes to resolving concurrently made changes. Even though Rational RequisitePro was not designed for such an environment, thus has no branch or merge capabilities included, it can provide support for this scenario to some degree. Because of the limitations, the use of such a scenario should be limited to projects where it is essential.

Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, and WebSphere®.

Discuss

Resources

Learn

  • Browse the RequisitePro page on developerWorks for links to technical articles and many related resources. The developerWorks Rational software landing page is also a good starting place.
  • Watch one of the Rational RequisitePro demos (scroll down).
  • Explore the RequisitePro Product Name Information Center.
  • Join the RequisitePro forum to ask questions and participate in discussions.
  • Download Rational RequisitePro for a free trial.
  • Check out agile development capabilities of IBM® Rational® Requirements Composer, which can help your entire team define, update, and management requirements throughout the product development lifecycle.
  • Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.
  • Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  • Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.
  • Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
  • Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  • Browse the technology bookstore for books on these and other technical topics.

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=468525
ArticleTitle=Manage development of document-based requirements in parallel with IBM Rational RequisitePro
publish-date=02182010