[Collapse]Collaborator 10
 [Expand]General Information/viewarticle/80040/
 [Expand]Getting Started/viewarticle/80359/
 [Expand]Collaborator Server/viewarticle/80060/
 [Collapse]Web Client/viewarticle/80107/
   Web Interface Client - Overview/viewarticle/80124/
  [Expand]Account Management/viewarticle/80076/
  [Collapse]Performing Reviews/viewarticle/80371/
    Action Items/viewarticle/80103/
    Creating a Review/viewarticle/80080/
    Review Summary Screen/viewarticle/80078/
    Sending Calendar Notifications/viewarticle/91141/
   [Expand]Reviewing Materials/viewarticle/80370/
    Types of Review Comments and Defects/viewarticle/80132/
    Review Chats, Comments and Defects/viewarticle/80079/
    FAQs/viewarticle/80390/
  [Expand]Searching & Reporting/viewarticle/80391/
   Troubleshooting/viewarticle/80368/
 [Expand]Desktop Clients/viewarticle/80151/
 [Expand]Version Control Integration/viewarticle/80048/
 [Expand]External Integrations/viewarticle/80340/
 [Expand]Techniques & Best Practices/viewarticle/80403/
 [Expand]Appendices/viewarticle/80117/
Updated: 12/23/2016 Applies To: Collaborator 10 Rating: AverageAverageAverageAverageAverage 2 vote(s) Click to rate: PoorNot badAverageGoodExcellent

Web Client > Performing Reviews

Top |Previous |Next

Review Chats, Comments and Defects

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.

Making Conversation -- Chatting at particular lines, coordinates, cells

To start a new chat session, just click on a desired location (line, coordinates, cell) and start typing. The interface will open up automatically and accept your chat message:

ws-review-sidebyside-chat-start

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:

ws-review-sidebyside-chat-one

Notice how the conversation is now threaded by line (112) and how a little icon appears next to the source 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".

ws-review-chat-linkify-file-and-line

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

ws-review-sidebyside-chat-unread

To clear this "unread chat" state, send a chat message back to the other user. You can also click the green checkmark button to 'Accept' the comment or the 'Mark Read' button.

"Accept" means whatever you want it to mean. If you want, you can never use the Accept button at all. The actual effect of clicking "Accept" on a conversation is to mark that conversation read, and to put a green check mark next to that conversation in the Inspection page (main review page with list of files). Those check marks are visible to all users.

Many people use "Accept" as sort of a bookmark within the review to keep track of what files they have already looked at. Some people use it to mean explicit agreement with the conversation (as opposed to simply not replying, which is implicit agreement).

If you want to clear the "unread chat" state without saying something, click the Mark Read button (there is also a 'Mark All Read' button at the bottom of the chat pane):

ws-review-sidebyside-chat-markread

Redacting Comments

People have a knack for typing things that for various reasons they should not.

ws-overly-harsh

When you do this, you can redact your harsh, erroneous or otherwise inappropriate statement by clicking the "X" to the right of your comment. The "X" will appear when you mouse-over the specific comment you would like to redact. The comment will then be displayed in a much more difficult to read manner.

ws-harsh-comment-redacted

This styling is meant to deter the casual reader from actually reading the text. You cannot undo redacting a comment. If you have accidentally redacted a comment, you can copy the text from the redacted comment into a new comment. System administrators are allowed to redact any comment. Normal users are allowed to redact comments they authored.

Creating Defects -- indicating that something is wrong

When you want to indicate that there is a problem that needs to be fixed -- not just more chat -- you open a defect. Do this using the As Defect drop-down below the comment field:

ws-review-sidebyside-defect-create

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.

ws-review-sidebyside-defect-create-fields

Once the defect is created, it is added to the chat area and a defect log is started on that line:

ws-review-sidebyside-defect-created

Every defect is given a unique number, on the server; in the example above the number is D1. There will only ever be a single defect numbered D1, 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.

You can Edit a defect by clicking [Edit] in the defect log. Or Delete a defect by clicking [Delete] (available after clicking Edit). All of these activities will be logged into the chat conversation area as an audit trail of what happened.

Warning: 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". This process is described next.

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

Warning: 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.

Verifying that 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, click [Mark Fixed] to indicate this fact. The conversation area and defect log will be updated to reflect this new state:

ws-review-sidebyside-defect-fixed

Externalizing 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.

The answer is to use the [Track Externally] link as shown below:

ws-review-sidebyside-defect-externalized

This does two things. First it prompts you to create a new defect in your external issue tracker, then allows you to type in the associated issue ID in a field. Second, it changes the state of the defect from "Open" to "Tracked Externally".

This special state tells everyone else that (a) the review can complete but (b) the problem was not fixed during the review and (c) how to find the external issue for further auditing. The state appears on the Review Overview screen with a special icon:

ws-review-overview-defectlog-externalized

You can always undo the "Tracked Externally" state by clicking on the associated link [REOPEN]. This link will be in the place where [Track Externally] was. This will re-open the defect, restoring it to the state it had before the externalization.




© 2019 SmartBear Software. All rights reserved.
Email Send feedback on this document