Commenting on artifacts

A comment is a textual discussion item that is associated with an artifact or an element within an artifact. You can use comments to provide team feedback during the development of an artifact. Comments are displayed in the Comments section of an artifact sidebar, in the Recent Comments section of the project page sidebar, and in Recent Comments for Me on the User Dashboard.

About this task

You can comment on an artifact as a whole (by using artifact-level comments) and on specific elements within the artifact. In documents, 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 visible to all team members who have access to the artifact.

When creating a comment, you can direct it to one or more users, in which case it will be displayed in their dashboards. If your server has e-mail notifications set up, you will get e-mail when comments are directed to you.

A comment and its replies are maintained as a group in the comments section. A comment's replies are indented underneath its top-level comment. The number next to the comments icon in an artifact toolbar displays the total number of comments in the artifact. Click the icon to highlight the comments in the artifact or add a new comment. You can also view comment totals in the Artifact project page when you view the artifacts list with details. You can add a comment there without opening the artifact.

When you select a comment in 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.

Comments made on embedded or reusable artifacts can only be seen in the context in which they were made. For example, if you embed a sketch in a document, comments made on the embedded sketch in the document cannot be seen when viewing the sketch in its own editor.

The following table describes additional tasks for managing comments.

Table 1. Controls and associated tasks in the Comments section of the sidebar
Task Icon Steps
Expand/collapse a comment.   Click the header portion of the top-level comment. The comment's text and its replies are shown or hidden.
Expand or collapse comments. Click the Expand All and 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 click the Comments icon in the artifact header and select Add Comment to Artifact.

To create a comment associated with an element, select an element in the editor and click the Add comment icon above the element. You can also add a comment to a selected element by clicking the Comment icon in the sidebar. If no comments are selected, you can click the option to Create a New Comment for <element>.

To add a comment in a document or requirement, right-click in a paragraph or bullet item and click Add comment.

To create a reply, select a comment and click the Comment icon or right-click the comment and click Reply to <comment>.

Highlight elements or paragraphs in the editor that have associated comments.

Select this icon to highlight all elements in the artifact editor that have comments. When working with a document all paragraphs that contain comments are highlighted.

The number of comments 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.

Select the icon again to remove the highlighting.

Filter the comments in this view.

Click the Filter icon to limit the display to only those comments that include or match your criteria.

Filter criteria includes priority, comment author (By), targeted recipient for the comment (For), resolution state (unresolved only, be 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 display.

Click Clear filters to show all comments.

Resolve a comment, indicating that the comment requires no further action or reply. To resolve a comment, select the comment and click the Comment icon or right-click the comment and select Resolve Comment. Resolved comments are displayed with light gray text. After a comment is resolved, you can reopen it as well as reply to it.
Edit a comment. To edit a comment, select the comment and click the Comment icon or right-click the comment and select Edit Comment. A comment can only be edited by the user who created it.
View full comment text.   Long comments are truncated in the Comments view. To see the full text just hover over the comment.
Sort and group comments. Click the Sort and Group icon in the Comments section to access sorting and grouping options. The Author refers to the originator of the original comment. The Date refer to the date of the last activity for the comment, including replies.
Display the Recent Comments section in the project page sidebar.   Open a project using the Open button in the editor toolbar. Expand the sidebar in the project page by clicking the arrow in the upper right. Expand the Recent Comments section sidebar.
Display the Recent Comments for Me section in the project page sidebar.   Open your Dashboard using the Open button in the editor toolbar. Comments that have recently been directed to you are displayed in the Recent Comments for Me section.
Deleting comments.   Comments are never deleted even if the associated element is deleted. These comments are now marked with "(element not in this revision) in the comment title. These comments can be hidden in the comment section by using the (Hide comments on orphaned elements) option in the filter panel.

Feedback