There are two main types of messages in Collaborator: comments and defects.

Comments may hold any information concerning the review: a question, a clarification, a remark, an encouragement, whatever else. These are the major means of communication during the review process.

Defects indicate a problem that needs to be fixed. Defects have some text that describes the problem and also 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.

Every defect is given a unique number on the server. There will only ever be a single defect with the given ID, no matter how many defects, documents or reviews exist on the server.

All defects found during a review are listed in the Defect Log section of the Review Screen, (so you will not overlook any of them).

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.

Color Highlighting of Comments and Defects

To indicate the status of the comment or defect they are highlighted in different colors. The following color notations are used for message backgrounds in the Chat pane, for line indents of text files, for pushpins and for cell borders:

Color	Meaning
Blue	The currently selected conversation.
Red	An open defect.
Yellow	An unread comment.
Green	A fixed defect or an external defect.
Gray	No defects or rejected defects.

Global and Content Specific Comments and Defects

Comments and defects can be global or context specific. That is, they may relate to the entire review, or to certain review materials or even to a particular line, coordinate or cell in one of the reviewed files.

Collaborator has the following sub-types of comments and defects:

Global (Review Chat)
Annotation
Overall for File Revision or URL
Line
Coordinate (Pushpin)
Label
Cell
Element

Global Comments and Defects (Review Chat)

These comments or defects relate to the entire review as a whole (not to some specific review materials). Can be used with all reviews.

Global comments and defects are displayed in the Chat section of the Review Screen. Besides that, this section displays some helper information: who has marked checklist items, who has signed the review, information about pull requests and branches and so forth. Support rich-text and Markdown formatting and user mentioning.

To add comments to the Chat section, simply type your comment in the text box and click Add. To add defects, type the defect description, click Add As Defect and fill in the required fields.

Annotation Comments

These type of comments provide short description (annotation, notes or some other short info) about a particular file revision or URL. Can be used with all review materials. Defects cannot be of annotation type.

Annotation comments are displayed in the Notes column of the Review Materials section of the Review Screen.

To add annotation comments, click the plus button in the Notes column, enter annotation text and click Save.

Overall Comments and Defects for File Revision or URL

These comments or defects relate to a particular file revision or URL (as a whole, but not to some specific part if it). Can be used with all kinds of review materials.

Overall comments and defects are displayed in the Overall section of Chat pane in the Diff Viewer. Besides that, this section displays some helper information: a notice that a new file revision has been uploaded, a notice that the revision was approved and so on. Support rich-text and Markdown formatting and user mentioning.

To add comments to the Overall section, simply type your comment in the text box and click Add. To add defects, type the defect description, click Add As Defect and fill-in the required fields.

Line Comments and Defects

These comments or defects relate to a particular line within a file. Can be used with source code files and any other text-based files. Multiple comments and defects can relate to the same line of text.

Line comments and defects are displayed in the Chat pane of the Diff Viewer. Support rich-text and Markdown formatting and user mentioning.

To add line comments, click the desired line of text in the content view, type your comment in the text box and click Add. To add defects, click the desired line of text in the content view, type the defect description, click Add As Defect and fill in the required fields.

To add a comment on multiple lines, click and drag to select the desired range of lines in the content view, type your comment in the text box and click "Add".

Several comments can start from the one line (e.g, comments for the lines 10-15, 10-18, 10-12 could be created). Comment cannot be attached to a collapsed block of lines ('skipped lines ...'), in this case Collaborator selects lines from where users starts selection to line before the collapsed block.

Coordinate Comments and Defects (Pushpins)

These comments or defects relate to particular coordinates within a file. They can be used with word-processing documents, presentations, PDF documents, images and vector graphics. Multiple comments and defects can relate to the same coordinate.

Pushpin comments and defects are displayed in the Chat pane of the Diff Viewer. Support rich-text and Markdown formatting and user mentioning.

User can select some area (rectangle) in the document and create a conversation, connected to this area.

To add pushpin comments, click the desired location in the content view, type your comment in the text box and click Add. To add defects, click the desired location in the content view, type the defect description, click Add As Defect and fill in the required fields.

Pushpins created via Web Client or command-line client display an integer number in their head: The number corresponds to the order in which that pushpin was added to the document page or image.

Pushpins created via Eclipse Plug-in do not display any ordinal numbers:

Label Comments and Defects

These comments or defects relate to an arbitrary label within a file. Can be used with word-processing documents, presentations, PDF documents, images, vector graphics and Simulink models. The label text must describe the content (for example, "Section 5.1 on page 23") it relates to because label comments/defects do not have any other markers that bind the content and the label. Multiple comments and defects can relate to the same label.

Using labeled locations decreases the confusion that can occur when large changes occur in a document or image resulting in the pushpins not being adjacent to the corresponding context. Label text may not be updated.

Label comments and defects are displayed in the Chat pane of the Diff Viewer. Support rich-text and Markdown formatting and user mentioning.

To add label comments, scroll the Chat pane to the Start conversation at box, specify label text and text of the comment and click Add. To add defects, perform the same steps as for label comments, but click Add As Defect and fill in the required fields.

Cell Comments and Defects

These comments or defects relate to a particular cell within a spreadsheet. Can be used with Spreadsheet files. Multiple comments and defects can relate to the same cell. Conversations on cells are displayed in alphabetical order by sheet name, not in the sheet order found in the version content. The name of the chat includes the name of the sheet followed by the location of the cell being discussed. For example, 3sheetC10.

Cell comments and defects are displayed in the Chat pane of the Diff Viewer. Support rich-text and Markdown formatting and user mentioning.

To add cell comments, click the desired cell in the content view, type your comment in the text box and click Add. To add defects, click the desired cell in the content view, type the defect description, click Add As Defect and fill in the required fields.

Element Comments and Defects

These comments or defects relate to a particular elements of a Simulink model: block, property, line and so on. Can be used with Simulink models. Multiple comments and defects can relate to the same element.