30 productivity tips from the developers of IBM Rational Requirements Composer: Part 2. Collaboration

Tips for adding comments and links

IBM Rational Requirements Composer fosters collaboration by offering universal tools and views to search for, comment on, and define and navigate links between artifacts of any type. This exploration of these common facilities is punctuated by specific tips from the developers of Rational Requirements Composer to help you use this software more productively. Analysts with this knowledge will spend less time opening artifacts unnecessarily and retyping redundant information and more time perfecting their customers' requirements. This is Part 2 of a three-part series.

Lynne P. Kues (lynne_kues@us.ibm.com), Advisory Software Engineer, IBM Corporation

Lynne Kues photoLynne Kues, an advisory software developer with the IBM Rational Product Development group, is working on the Web client for Rational Requirements Composer. Before joining Rational group, Lynne spent most of her time developing IDEs and GUI toolkits. She was a developer on the Eclipse UI, SWT, eSWT, and VisualAge for Java teams. She lives in Asheville, North Carolina, in the U.S.



David E. Murray (demurray@us.ibm.com), Staff Software Engineer, IBM

Author1 photoDavid Murray is a member of the Common User Interface team for IBM Rational Requirements Composer. He was primarily responsible for the project home page and Search view in the rich client. David graduated from the Rochester Institute of Technology in 2004 with a bachelor's degree in computer science. Before joining the Rational Requirements Composer team, he worked on the editor for the Enterprise Generation Language (EGL) component of IBM Rational Business Developer, where he gained experience in delivering streamlined software for less-technical business developers.



03 June 2009

Also available in Chinese

In Part 1, about navigation, we explored the various ways that an artifact can be located and opened in an editor. Now we turn your attention to what you can do with an artifact after it has been opened.

In Rational Requirements Composer, the features that you use to comment on artifacts or elements within them and to link to artifacts created by other members of your team are universal. The editor for every kind of artifact — even those artifacts not native to Rational Requirements Composer (images, Microsoft® Word® documents, and so forth) — include the same controls in the header and sidebar to view and manage the artifact's comments, links, and requirements. The sections that follow describe how to make the best use of these features.

Tips for adding comments

Comments sidebar view

The Comments sidebar view shows all of the comments for a particular artifact. Comments can be created from either of these areas:

  1. The editor area of an artifact, by using the Add CommentAdd comment icon toolbar button (left control in Figure 1) or the drop-down menu for an element.
  2. The Comment menu (right button in Figure 1) in the Comments sidebar view. The Comment menu is context-sensitive, based on what is selected in the editor area of the artifact.
Figure 1. Creating a comment
Comments menu view

Options for creating a new comment for the active element ("Mastercard" label in the previous screen capture) and for replying to the selected comment are in the Comment menu. You can display the Comment menu either by using the drop-down tool item on the sidebar toolbar or by using a right mouse click within the sidebar.

Tip 1:
Before writing a comment that is specific to an element in the artifact (for example, a label in the user interface sketch or a paragraph in a document), click that element to select it. When your teammates click the comment later, that element will be selected for them.

The Comments sidebar also contains an option for creating a comment for the artifact (as opposed to commenting on an element within the artifact). Artifact-level comments are created by using the Create a New Comment for the Artifact action. To create comments for non-Rational Requirements Composer resources, use artifact-level comments.

Rich text comments

The Add Comment window (Figure 2) supports a spelling checker that is enabled by default, as well as rich text formatting and link creation.

Figure 2. The Add Comment window
Formatting options highlighted

Tip 2:
Where appropriate, augment your comments with rich text and links to make navigation easier for people who read the comment. Take advantage of the spell-checking feature, too.

You can navigate to links within comments from the Comments sidebar. The comment shown in Figure 3 has two links.

Figure 3. A comment with links
Screen segment that shows links

Filtering comments

As artifacts are defined, reviewed, and revised, the number of comments about the artifact will grow. You can use filtering to limit which comments are displayed in the sidebar. For example, you might be interested only in comments within a certain time period, or you could be interested only in comments directed to you. Use the Filter toolbar button in the Comments sidebar to filter comments.

The Comments sidebar sections will indicate when comments are filtered. In the screen capture in Figure 4, three comments meet the specified criteria and two comments are filtered out, as indicated by the "(3 of 5)" label.

Figure 4. Filtering indicated in the Comments sidebar section
'Comments (3 of 5)' highlighted

Tip 3:
Use the filtering controls in the Comments sidebar to view only those comments that are important to you, such as those addressed to you or created within the last week, and so forth.

When filtering comments, the comment and all replies will be considered, and the originating comment for the reply will always be displayed. In Figure 5, Comment 1 is shown because we were filtering by "Janet Thompson," and Janet replied to the original comment.

Figure 5. Replies to an unfiltered comment
Comment 1 shows a reply from Janet Thompson

The Highlight All action takes filtering into account. In Figure 6, only those elements that have comments that show in the Comments sidebar are highlighted. Elements with comments filtered out are not highlighted.

Figure 6. Highlighted commented elements
Screen capture with Comments sidebar on right

Sorting and grouping comments

Comments can be sorted and grouped within the Comments Sidebar. For example, you can use the Group by Artifact Element option to view comments as they relate to the particular elements in a diagram.

Figure 7. Comments grouped by element
Comments for the <EndEvent1> element only

You can also sort and group by Author and by Date.

  • When sorting and grouping by Author, the author of the top-level comment will be used as the basis of the operation.
  • When sorting and grouping by Date, the top-level comments and all of its replies will be considered; therefore, the date of the last activity for the comment (including its replies) will be reflected.

In the Figure 8, the comments are sorted by Date Last Modified (most recent first). "Last Modified" is the key point here. Comment 4 was made on December 9, 2008, so the comment itself is less recent than that of Comment 10, which was made on January 6, 2009. However, the comment made earlier (4) appears before the later one (10) because the earlier comment has the latest reply. Therefore, Comment 4 ends up before Comment 10 in the display.

Figure 8. Comments and replies sorted by date
Comments in this order: 4, 10, 7, 6

Tip 4:
Group or sort comments by Date Last Modified to call to attention to comment threads that are "active" (comments or replies that have been made recently).

Sending e-mail from a comment

Each comment includes the name of the user who wrote the comment and the name of the user that the comment is directed to (if specified). Left-click the user name to send e-mail to that particular user.

Figure 9. Clicking on User Name to send e-mail
'Send Email to User' shows after clicking on name

Resolving multiple comments

The Comments sidebar supports multiple selections. To select multiple comments, use the Ctrl key while selecting a comment. The Resolve Comment action in the context menu is available when one or more comments are selected, so multiple comments can be resolved in one operation.

To resolve all comments for an element, select the element within the artifact editor area. This action will select the element's associated comments in the sidebar. In the screenshot below, three comments are associated to the Validate Credit Card task. These comments are selected in the sidebar when the element is selected. The Resolve Comment action can then be executed to resolve all of the element's comments.

Figure 10. Selecting multiple comments
Show selecting multiple comments

Tip 5:
Use Ctrl to select multiple comments and resolve them all at once. To resolve all comments for an element, select that element and resolve the comments that are highlighted as a result.


Links sidebar view

The Links sidebar view shows all the links to and from a particular artifact. Within the view, links are displayed in the following format:

Target Artifact (from Source Element)

where Target Artifact is the artifact that you are linking to (destination) and Source Element is the element that you are linking from (origin).

Links can be created from the editor area of an artifact by using the element's context menu or by using the Link to other artifacts toolbar button (Show linking button) for an element that is in a diagram-based artifact.

Links can also be created from the Links sidebar view (Figure 11). The Links menu on the Links sidebar is context-sensitive based on what is selected in the editor area of artifact.

Figure 11. Create a link for an element or the artifact
Links sidebar screen capture

The Links sidebar also contains an option for creating a link for the artifact (a link where the artifact is the source of the link, not an element within the artifact). You can create artifact-level links by using the Create a New Link for the Artifact action. Artifact-level links are particularly useful for defining links from resources that are not native to Composer.

Filtering links

Within the Links sidebar view, you can filter links according to the type of the link's target artifact. Use the Filter toolbar button (the three right-pointing arrows shown in Figure 12) in the Links sidebar to filter links.

Figure 12. Filter the links that are displayed in the Links sidebar
Filter button icon

Tip 6:
Filter links in the Links sidebar to quickly find references to artifacts of a particular type (for example, a Microsoft Word document).

The Links sidebar sections will indicate when links are filtered. In Figure 13, four outgoing links are filtered out and 5 of 9 are showing.

Figure 13. Outgoing links displayed with some links filtered
9 outgoing links total but only 5 listed

The Highlight All action takes filtering into account. In Figure 14, only those elements with links that show in the Links sidebar are highlighted. Elements with filtered out links will not be highlighted.

Figure 14. Only elements with links that are not filtered out are highlighted
Icon shows a highlighter pointing to a page

Modifying links

Within Rational Requirements Composer, each artifact is identified by a permalink string, which is a unique identifier that is not derived from the artifact name nor its location. Therefore, if an artifact is renamed or moved to a different folder, links that point to the artifact will be preserved.

Tip 7:
Don't be concerned about links to an artifact when you rename that artifact or move it to another folder. Existing links to it will not be affected.

You can modify existing links by using the Edit option from the Links pop-up view (Figure 15). You can open that view by using the Link to other artifacts button on the element toolbar or in the element's drop-down menu.

Figure 15. Indication that an element has a link when it is selected
'Edit' icon shows pencil and paper

To edit an existing link, select the link in the view and use the view's drop-down menu. The Edit Link action will open the "Link to" dialog window, where the link description, the type of link, and the link target can all be modified.

Figure 16. Modifying an existing link
'Edit Link' selected in drop-down menu

Artifact-level links can be modified from the Links sidebar. Use the Manage Artifact Links menu item (Figure 17) from the Links button on the sidebar toolbar. This will open a Links Popup view that lists all artifact-level links. Note that this popup view lists only artifact-level links, not all of the links for the artifact. Links that originate from elements within the artifact have their own links popup view that can be opened via the element's context menu or the Link to other artifacts button on the element's toolbar.

Figure 17. Modifying or deleting links for the top-level artifact
'Manage Artifact Links' selecte

Drag items to create links

You can drag and drop resources onto the following artifacts to create links:

  • Actor
  • Business Process Diagram
  • Document
  • Requirement
  • Use Case
  • Use Case Diagram

Use the Project Explorer or the Search view to drag artifacts to create links. In diagram-based editors, a light-gray background will indicate which element the link will be created for (see Figure 18).

Figure 18. Drag an artifact onto a diagram element to create a link
'Shop for CD' element highlighted by gray

You can also create artifact-level links for a diagram by dropping the target artifact onto the empty space in the diagram.

Tip 8:
When decorating an artifact with links to several different other artifacts, consider bringing up the other artifacts in either the Project Explorer or the Search view and adding the links by dragging. If you create links in the editor instead, you will need to navigate to each target artifact in the "Link to" dialog. Dragging artifacts will save time, because there is no need to perform this navigation for every link.

For document-based editors (actor, document, requirement, use case), a red vertical line will indicate where that the link will be created in the document. For document-based editors, artifacts can also be embedded in the document by holding down the Ctrl key when you drop the artifact on the target.

Figure 19. Embed an artifact by dragging it onto a document while holding the Ctrl key
Red vertical line

Linking and requirements

Associating requirements with artifacts and the elements within an artifact is an operation that is separate and distinct from creating links. When creating links, the Choose Existing Artifact panel on the "Link to" dialog will filter out requirement artifacts, and the Create New Artifact panel will not include the requirement type. To associate a requirement with an element within an artifact, use the Mark as Requirement action (Figure 20). This action is on the context menu for artifact elements.

Figure 20. Extracting a requirement from a diagram element
'Mark As Requirement' context menu

You can also associate requirements with an element by using the Show Requirements icon on the element's toolbar (Figure 21).

Figure 21. Manage links for an element through the control on its toolbar
Icon: Yellow circle in square brackets

Requirements that are related to an artifact appear in a separate sidebar. The Requirements sidebar operates like the Links sidebar. You can choose from Highlight All, Filter, or Sort actions, and navigation to the source and target element is available. Notice that the Requirements sidebar (Figure 22) does not include Outgoing and Incoming sections like the Links sidebar does. When a requirement is associated with an artifact, the artifact will appear as an Incoming Link in the Links sidebar for the requirement.

Figure 22. The Requirements sidebar
List of linked requirements

To associate requirements with the artifact as a whole, use the Create a New Requirement for the Artifact action from the Requirements menu on the Requirements sidebar.

Figure 23. Extracting a requirement from an entire artifact
Option selected on menu

You can manage and edit artifact-level requirements by using the Manage Artifact Requirements action from the Requirements menu on the sidebar. This action opens a Requirements view that lists all artifact-level requirements.

Figure 24. Modify or delete requirements for the top-level artifact
Requirements menu

Notice that this pop-up view lists only artifact-level requirements, not all of the requirements for the artifact. Requirements that are associated with elements within the artifact show in a separate Requirements pop-up view, which you can open by using either the element's context menu or the Show Requirements icon on the element's toolbar.

Placeholder links

A placeholder link is a link with an initially undefined target. Suppose you are meeting with a user to discuss the requirements for a particular application. During the meeting, you start to discuss some of the user interface design, and you decide to create a User Interface Sketch to capture what is being discussed. As you are defining the elements of the sketch with the user, it becomes apparent that a Document artifact is necessary to define the validation rules for a particular field. Rather than having to explicitly create a new Document artifact for this additional information, you can create a placeholder link for the field and continue with the work at hand (designing the user interface). You can capture the validation rules later.

Tip 9:
Use placeholder links to capture relationships to artifacts that do not yet exist as a way to rapidly prototype requirements.

To create a placeholder link, use the Links pop-up view and specify a link description, but do not specify a target for the link. In Figure 25, a link for shipping and handling rules is being created, but the artifact that defines those rules does not yet exist, so just a link description is specified.

Figure 25. Add a link without defining a target
Links pop-up view

In the Links sidebar, placeholder links are identified with a diamond-shaped icon . To specify the target for a placeholder link, you can click the link in the Links sidebar, or you can edit the link in the Links pop-up view. Both of these actions will open the "Link to" window, where you can specify the target for the link.

Figure 26. A placeholder link
Showing a placeholder link

You can also use placeholders when associating requirements with an artifact. In Figure 27, the Cardholder name field has a placeholder requirement for Cardholder Validation.

Figure 27. A placeholder requirement
Requirements window

Special links

Several operations create relationships between artifacts, and Rational Requirements Composer automatically captures those relationships by creating a link in the Links or the Requirements sidebars. The operations that create links are listed by artifact type:

  1. Business Process diagram
    1. Elaborating a task with a Use Case diagram or sketch
    2. Associating a System use case with a task
    3. Associating a process with a subprocess
  2. Use Case diagram
    1. Using a shared actor or shared use case
    2. Elaborating a use case with a storyboard
  3. Glossary
    1. Specifying a related or synonym term
  4. Requirement
    1. Managing a requirement in IBM® Rational® RequisitePro®
  5. User Interface sketch
    1. Reusing an image, part, or sketch
  6. User Interface part
    1. Reusing an image, part or sketch
  7. Storyboard
    1. Associating a sketch with a frame
  8. Text-based artifacts (document, actor, use case, requirement)
    1. Inserting an image or artifact (if the inserted artifact is a requirement, this association will be added to the Requirements sidebar)
    2. Embedding a requirement by using Mark As Requirement (this association will be added to the Requirements sidebar)
    3. Linking to a term

Notice that these links cannot be directly edited or deleted. Instead, Rational Requirements Composer manages these links as information about the relationship changes, or the relationship is removed.

Tip 10:
When reading or reviewing an artifact written by a peer, take a look at the outgoing and incoming links and requirements to see whether there are related artifacts that are of interest to you.


Summary of tips

Tip 1: Before writing a comment that is specific to an element in the artifact (for example, a label in the user interface sketch or a paragraph in a document), click that element to select it. When your teammates click the comment later, that element will be selected for them.

Tip 2: Where appropriate, augment your comments with rich text and links to make navigation easier for people who read the comment. Take advantage of the spell-checking feature, too.

Tip 3: Use the filtering controls in the Comments sidebar to view only those comments that are important to you, such as those addressed to you or created within the last week, and so forth.

Tip 4: Group or sort comments by Date Last Modified to call to attention to comment threads that are "active" (comments or replies that have been made recently).

Tip 5: Use Ctrl to select multiple comments and resolve them all at once. To resolve all comments for an element, select that element and resolve the comments that are highlighted as a result.

Tip 6: Filter links in the Links sidebar to quickly find references to artifacts of a particular type (for example, a Microsoft Word document).

Tip 7: Don't be concerned about links to an artifact when you rename that artifact or move it to another folder. Existing links to it will not be affected.

Tip 8: When decorating an artifact with links to several different other artifacts, consider bringing up the other artifacts in either the Project Explorer or the Search view and adding the links by dragging. If you create links in the editor instead, you will need to navigate to each target artifact in the “Link to” dialog. Dragging artifacts will save time, because there is no need to perform this navigation for every link.

Tip 9: Use placeholder links to capture relationships to artifacts that do not yet exist as a way to rapidly prototype requirements.

Tip 10: When reading or reviewing an artifact written by a peer, take a look at the outgoing and incoming links and requirements to see whether there are related artifacts that are of interest to you.

Resources

Learn

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=394113
ArticleTitle=30 productivity tips from the developers of IBM Rational Requirements Composer: Part 2. Collaboration
publish-date=06032009