Commenting

Requirements Portal supports commenting within your requirement projects. A comment is a user-added note that is assigned to a specific requirement and may be replied to by other users. Comments promote collaboration between users without altering the shared data itself, because comments are stored by the Workspace independently of that data. You can mention one or more people or groups in the comment. A comment can also be assigned to a Workspace member.

Comments are posted, replied to, and managed directly within the requirements table using a contextual commenting window. Comments are also presented on the Comments and Tasks pane, which is presented on the right-hand side and provides more of an overview/navigational instrument, rather than the operational interface. Use the  control at the top right to toggle the display of the Comments and Tasks pane.

Placing a Comment

Comment placement mode can be entered in one of the following ways:

• Click the  button at the top of the Comments and Tasks pane and then use the resulting placement cursor () to select a requirement line for commenting.

• Click the  button in the line for the requirement and select the Comment command from the menu that appears.

In each case, a commenting window will be presented, with which to define the comment in context with the chosen requirement. Type your comment in the field provided. You can mention one or more people or groups in the comment. Type the @ character in the comment field to quickly access a list of members in the Workspace. A comment can also be assigned to a member. For more information on these additional features, see the Working with the Contextual Commenting Window section.

With the comment entered, any mentions added, and assignment made if required, click the  button beneath. The comment will be committed, appearing in both the contextual commenting window and the Comments and Tasks pane.

The following sequence image shows the addition of an example comment to a requirement, along with adding a mention of a team member and assigning a task to them (see below for details).

Working with the Contextual Commenting Window

The following points relate to working with comments and the interface's contextual commenting window:

• The commenting window can be accessed by clicking the comment entry in the Comments and Tasks pane.

  

• The window can be freely moved by clicking and dragging its top bar.

• Use the buttons at the top left of the commenting window to sequentially cycle to the previous and next comments respectively.

  You can also use the Shift+Left Arrow and Shift+Right Arrow to cycle to the previous and next comments respectively.

• Once an initial comment has been made, the commenting window, when accessed, will be ready for entry of a reply. Type your text in the field provided, then click the button to commit. To exit without replying, press Esc.

• You can mention a person or group within a comment. Enter the @ character to access a pop-up listing of all members of the Workspace team. Alternatively, search for the group or person (the latter by their name or email) by typing @ followed by one or more characters – a list of matching groups, team members, and people outside of the team (but within your organization) will be presented from which to choose. You can either click on an entry to add it or use the Up Arrow / Down Arrow keys and press Enter to add.

  A mentioned person who is either a team member or who is a member of a mentioned group will receive a notification email of the comment.

  

  You can mention any person or group within a comment. Enter the @ character to access a listing of all Workspace members and groups.

  

  Alternatively, enter @ and start typing to search for a group or person. The dynamic listing includes Workspace members, others within your organization, and groups defined for the Workspace.

  

  When replying to a comment you also can assign a task to the newly mentioned person.

  

  The required person, people, or groups will appear mentioned in the comment text (by their name where possible).

   

• You can assign a task to a person who has been mentioned. Enable the Assign a Task to option accordingly – this defaults to the first-mentioned person, or if no mention is included, to yourself (Me). Alternatively, use the drop-down menu to choose a different Workspace member to assign the task to. The assigned person is shown in the Comments and Tasks pane entry as their user profile image/letter, with an associated task reference. The task assignment can be changed or removed when editing the comment.

  

  Where a task is associated with a comment, its window's upper border includes:

  • an icon (image/letter) indicating the member that has been assigned to the comment's task. Select the icon to reassign the task to a different Workspace member from the drop-down list.

  • the task's alphanumeric reference, composed of the requirement identifier with a task number suffix. Click on the reference to cross-probe to that task entry in the Workspace Tasks page.

    From the Workspace Tasks page, you can also see and change the task priority (Medium by default).

  • the task's current activity status (To Do, In Progress, Resolved), which can be changed from the associated drop-down menu ().

  

• A task can be added to an existing comment using the Convert to Task option available from the window's  menu. The new task initially is assigned to you and can be changed to another Workspace member by selecting their entry from the drop-down list opened from the assignee avatar (top left).

  

• The commenting window will also accept an image file or captured screenshot pasted from the Windows clipboard. You can paste the screenshot (or copied image file) into the comment field before or after any text notes and user mentions. The image graphics are displayed in the body of the commenting window – click on the image to open it for viewing at full-size. The placed comment's entry in the Comment and Tasks pane will include a related includes images note.

  

• A comment can be edited or deleted, through the commenting window only, using the Edit and Delete commands respectively. These are available from the menu associated with the  control. Note that these commands will only be available for a comment that you yourself have made – you cannot edit or remove a comment made by another user. If you edit an existing comment, make your changes, then click the  button to commit. To exit without applying any changes, press Esc.

  If you delete a comment, be aware that all associated replies also will be deleted.

  

• When the commenting window is accessed, only the initial and latest comments in the thread are presented. To see all comments in the thread, click on the available control between these entries. Use the scrollbar to browse through all comments.

  

• A comment can be resolved (or made active again) by toggling the control at the top of the commenting window. Where the comment has an assigned task, its current status can be changed to Resolved (or another level) from the status drop-down menu. Resolved comments are not shown in the Comments and Tasks pane by default but can be exposed through its show/hide pins option – see the next section for more information.

  

Working with the Comments Pane

The following points relate to working with comments and the interface's Comments and Tasks pane:

• The Comments and Tasks pane facilitates an overview/navigational tool for comments across the project, rather than the operational interface of posting, editing and replying. That functionality is solely left to the contextual commenting window.

• At the top of the Comments and Tasks pane are controls that provide access to thread filtering controls, so that you can determine what is presented in the pane. Two levels of filtering can essentially be defined. The first, or primary level, allows you to control which user comments are displayed.

  

  The pane's filter options constrain the comment entries to:

  • Tasks only – only those comments that have been assigned as user Tasks, which are in turn available in the Tasks page flow.

  • Assigned to – only comments that are assigned to the user selections listed below. When a user checkbox is selected, the pane (and displayed document) will include only those comments that have tasks assigned to that user. Note that the currently signed-in user is included at the top of the list, regardless of any comment task assignments.

  The secondary level of filtering, which is applied in conjunction with the primary filtering method offers two options that allow you to hide all resolved comments or tasks (Unresolved only enabled) and/or to only show comments for the currently selected context (i.e., folder, specification, or section) rather than the entire project (Current context only enabled).

  

• Click the Notification Settings entry (at the bottom of the above options window) to access a window with which to configure which comments in the project you will receive email notifications for. Choose to receive notifications for all comment threads, no comment threads, or only those you are involved in (you started, replied to, or have been mentioned within).

  

• In terms of ordering of comment threads in the pane, again, there are two levels. Firstly, comments are ordered by the specification they are in, and this follows the same ordering as the Requirements structure in the left-hand project tree. Secondly, for each requirement, the comments are ordered by the date of their creation – in descending order.

• As you click on a comment thread entry in the pane, that comment will be opened in the contextual commenting window. The entry for the comment in the Comments and Tasks pane is also highlighted in blue. If you click on a comment that does not reside in the specification currently being viewed, then you will be navigated to that specification of residence.

  

• Each comment entry in the pane provides a summary of key information relating to that comment, as shown in the example below.