Commenting on artifacts

A comment is a textual discussion item that you can add to an artifact or an element within an artifact. You can use comments to provide team feedback during the development of an artifact. In the web client, comments are displayed in the Comments section of an artifact sidebar, in the Recent Comments section of the Artifacts page sidebar, and in Recent Comments for Me on the user dashboard.

About this task

The following table provides instructions for how to comment on artifacts by using the web client. You can also watch a movie that shows how to comment on artifacts.

You can comment on an artifact as a whole (by using artifact-level comments) and on specific elements in the artifact. Comments on artifacts become part of the stream and must be delivered before they are visible in other streams in a configuration. In rich-text artifacts, you can comment on the whole document (by using document-level comments), a paragraph, or an item in a bulleted list within the document. Comments are accessible to all team members who have access to the artifact.

When you create a comment, you can direct it to one or more users, so that it is displayed on their project dashboard. If your server has email notifications set up, you receive an email when comments are directed to you. For more information, see Configuring email settings.

A comment and its replies are maintained as a group in the comments section. Replies to a comment are indented under the top-level comment. The number next to the Comments icon

on an artifact toolbar displays the total number of comments on the artifact. Click the icon to highlight the comments on the artifact or to add a new comment. You can also view comment totals on the Artifacts page when you view the artifacts list with details. You can add a comment there without opening the artifact.

Note: Comments on reviews or on artifacts in a review behave differently and are not part of any stream or baseline.

When you select a comment on an artifact, its associated element is selected in the editor. When you select an element in an artifact editor, its associated comment is selected in the sidebar.

The following table describes additional tasks for managing comments.

Table 1. Controls and associated tasks in the Comments section of the sidebar in the web client
Task	Icon	Steps
Expand or collapse a comment.		Click the header portion of the top-level comment. The comment text and replies are shown or hidden.
Expand or collapse all comments.		Click the Expand All or Collapse All icons to show or hide the text and the replies for all comments in the Comments section.
Add or reply to a comment in an artifact.		To create a comment that applies to a whole artifact, in the Comments section of the sidebar, click the Comment icon and click Create a New Comment for the Artifact. You can also add a comment to a selected element by clicking the Comment icon in the sidebar and using the option Create a New Comment for <element>. To create a reply, select a comment and click the Reply icon .
Highlight elements or paragraphs in the editor that have associated comments.		Click the highlight elements icon to highlight all elements in the artifact editor that have comments. When you are working with a document, all paragraphs that contain comments are highlighted. The number of comments that are associated with each element or paragraph is also shown in the editor; this number is adjusted depending on your filter settings for the Comments section of the sidebar. To remove the highlighting, click the icon again.
Filter the comments in this view.		Click the Filter icon to limit the display to only those comments that include or match your criteria. The filter criteria includes priority, comment author (By), targeted recipient for the comment (For), resolution state (unresolved only, by default), and a date range for recent comments only. Click the Filter icon to collapse the filter section. Collapsing the filter section does not clear the filtering conditions; only those comments that match the filter criteria are displayed. To show all comments, click Show All.
Resolve a comment to indicate that the comment requires no further actions or replies.		To resolve a comment, select the comment, and click the Resolve Comment icon. Resolved comments are displayed with light gray text. After a comment is resolved, you can reopen it and reply to it.
Resolve a discussion thread, which resolves a comment and all replies to it.		To resolve a discussion thread, select the comment and click the Resolve Discussion Thread icon.
Edit a comment.		To edit a comment, select the comment and click the Edit Comment icon. Only the user who created the comment can edit it.
Sort and group comments.		Click the Sort and Group icon in the Comments section to access sorting and grouping options. The Author refers to who created the original comment. The Date refers to when the last activity occurred on the comment, including replies.
Display the Recent Comments section in the Artifacts page sidebar.		Open a project by selecting it from the Home menu. If necessary, expand the sidebar on the Artifacts page by clicking the arrow on the right. Expand the Recent Comments section sidebar.
Display the Recent Comments for Me section in the Artifacts page sidebar.		Open your dashboard by clicking the Dashboard menu. Comments that were recently directed to you are displayed in the Recent Comments for Me section.
Delete comments.		To delete a comment, select the comment, and click the Delete Comment icon. A comment can only be deleted by its author, and only if it has no replies. Comments are not deleted if the associated element is deleted. These comments are marked with (element not in this revision) in the comment title. To hide these comments in the comment section, click Hide comments on orphaned elements in the filter panel.