Review Chats, Comments, and Defects

Applies to Collaborator 13.6, last modified on May 25, 2021

Viewing differences between documents is merely the beginning. The key to reviewing documents is communication.

There are various global and content-specific types of comments and defects in Collaborator. See Types of Review Comments and Defects for detailed description of each type.

This topic describes how to communicate during a review.

Make Conversation – Chatting at Particular Files, Lines, Coordinates, Cells

To start a general conversation about some particular file, open the desired file in the Diff Viewer, type your comment in the Overall section and click Add. Comment could be in plain-text or use rich-text and Markdown formatting, they could also mention other Collaborator users.

To start a conversation about some particular location (line, coordinates, cell), just click the desired location and start typing. The interface will open up automatically and accept your chat message:

When you click Add, your message is transmitted to all other users and you have started a threaded conversation for that particular location (line, coordinates, cell). In this case, it would look something like this:

Notice that the conversation is now threaded by line 62 and that a chat icon ( ) now appears next to the source line where the conversation was made.

When you type the name of a file in the same review, it will turn into a link to that file. You can also link to a different line number in the current file by typing "line NNN", where NNN stands for the number of the line.

When another user chats on that same line, that message appears in yellow and yellow bubbles help make the conversation stand out as needing to be read. The screen updates immediately without the need to refresh the browser:

To answer a message, just type your answer in the chat window.

To clear the "unread chat" state without answering, click the Read button (there is also the Mark all read button at the bottom of the chat pane):

Accept Files and Comments

In addition to marking a conversation as read, you can also click the Mark Accepted button in the chat to accept the comment or file revision. The Mark Accepted button affects conversations/revision that is currently displayed in the After pane of the Diff Viewer. The button can be inactive when the conversation/revision is already accepted, or when the revision currently displayed in After pane actually precedes (is earlier than) the revision displayed in Before pane.

"Accept" means whatever you want it to mean.  If you want, you can never use the Mark Accepted button at all. The actual effect of clicking Mark Accepted on a conversation is to mark that conversation as read and to put a green check mark next to that conversation in the Review Material section of the Review Screen. Those check marks are visible to all users.

Conversation status icons in the Review Materials section
Conversation status icons in the Review Materials section

Some people use it to mean explicit agreement with the conversation (as opposed to simply not replying, which is implicit agreement).

Many people use "Accept" as sort of a bookmark within the review to keep track of what file revisions they have already looked at and agree with its changes.

  • When the author uploads new revision of a document, the accepted icon ( ) will change back to chat icon ( ) denoting that the participant has not yet approved changes in this new revision.

  • When the author uploads new revision of a source code or text file Collaborator acts a little bit smarter: if the respective line was not changed, the accepted icon ( ) will keep indicating that the changes were already accepted; otherwise the accepted icon ( ) will change back to chat icon ( ) denoting that the participant has not yet approved changes in this new revision.

Edit Comments

By default comment editing is disabled in order to keep all comments intact for auditing purposes. If the the Allow to edit/delete comments server option is enabled, review participants could modify their own comments. Comment could be modified unless it is followed by another participant's comment.

To edit a comment:

  • Mouse-over the specific comment you would like to modify and click Edit.
  • Modify comment text and click Save.

Delete Comments

People have a knack for typing things that for various reasons they should not. Afterwards, they may want to discard their harsh, erroneous or otherwise inappropriate statements.

To discard a comment:

  • Mouse-over the specific comment you would like to discard and click Delete.

Further behaviour depends on the the Allow to edit/delete comments server option. By default comment deletion is disabled in order to keep all comments intact for auditing purposes. In this case the comment will not be actually deleted, but it will be displayed in a much more difficult to read manner. This styling is meant to deter the casual reader from actually reading the text.

When the Allow to edit/delete comments option is enabled, a confirmation dialog is displayed and on agreement the comment is deleted permanently. Comment could be deleted unless it is followed by another participant's comment.

You cannot undo discarding/deleting a comment. System administrators are allowed to discard any comments. Regular users are allowed to discard their own comments.

Create Defects When Something is Wrong

When you want to indicate that there is a problem that needs to be fixed rather than simply discussed you open a defect. Do this using the Add as defect button below the comment field:

Besides the comment text, defects can have any number of additional fields. These are all completely configurable by the system administrator and can also vary depending on the review workflow that was originally selected for the review. Because this is completely configurable, this manual cannot say exactly what the fields will be or what they mean; ask your administrator for details. It is common to see fields like severity, type, checklist item, and phase-injected.

Once the defect is created, it is displayed in the Defect Log and Review Material sections of the Review Screen and in the Chat section of current file. The defect conversation is threaded. Open defects are denoted by red icon :

Every defect is given a unique number on the server; in the example above the number is D9. There will only ever be a single defect numbered D9, no matter how many defects, documents or reviews exist on the server.

You can have any number of defects on a single line; all will be logged into the list beneath the chat area.

The word "defect" has many connotations that are inappropriate for peer review. This does not mean the problem will be mirrored in an external issue-tracking system, and it does not necessarily mean it was a bug! Even "bad documentation" can be a defect.

A "defect" is just a way of identifying something that needs to be fixed.

Moreover, if the word "defect" has a negative connotation in your environment, your Collaborator administrator can change it to another term.

Verify Defects Have Been Fixed

Later, after the author has attempted to fix the defects and has uploaded the new files to the review, the reviewers will verify that the fixes do fix the defect and do not open more defects in the process.

When the fix is verified, locate the defect and click the Mark Fixed button in the defect pane.

The defect icon will change to green to denote that the defect have been fixed. The new state of the defect will be reflected in the Defect Log and Review Material sections of the Review Screen and in the Chat section of current file.

If the defect has re-appeared again in some subsequent revisions, you can reopen it by pressing the Reopen button in the defect pane.

Modify Defect Information

To modify defect information click the Edit button in the defect pane.

In the edit mode, you can change defect description and modify other defect custom fields. Also you can move the defect to external issue tracker (see next section for details on this). All of these activities will be logged into the chat conversation area as an audit trail of what happened.

Externalize Defects

Sometimes you decide that a defect should be fixed at a later date. You do not want to mark it fixed because it is not fixed yet. But you do not want to delete it either because it is still a defect.

In this case you can move the defect to the external issue-tracking system and mark the defect as external. This special state tells everyone else that (a) the review can be completed but (b) the problem was not fixed during the review and (c) how to find the external issue for further auditing.

You may either create the issue (ticket, work item) manually and link it afterwards, or create new item directly from Collaborator and link it automatically. The latter requires, that your Collaborator administrators setup and configure issue-tracking integration.

  • To link the defect to some existing issue (ticket, work item), press Track externally and specify the defect identifier in your external issue tracking system.

  • To create a new issue (ticket, work item), press Export issue and specify the defect details in the ensuing dialog.

Any of these actions changes the state of the defect from "Open" to "Tracked Externally".

The defect icon will change to blue to denote that the defect have been tracked externally. The new state of the defect will be reflected in the Defect Log and Review Material sections of the Review Screen and in the Chat section of current file.

Delete Defects

Sometimes people could create defects by mistake and may want to delete them afterwards.

It is tempting to delete a defect once the author has corrected the problem, but this is the wrong thing to do. You want to keep the defect record around, just mark it "fixed".

Delete a defect only if it turns out that it really was not a defect at all.

To delete a defect click the Delete button in the defect pane.

See Also

Types of Review Comments and Defects
Basic Concepts
Participate in Reviews
Rework Defects

Managing Feedback
 
Highlight search results