Jump to >

PDF Document Review

Often, writing code is only a small part of a software development project. Along the way, numerous documents are produced and discussed, including requirements documents, feature specifications, and technical documentation for end-users. The PDF Document Review feature in Power Pack allows you to apply the same peer review process to all of these as you do for your source code.

Creating a document review

To review a document, you need to start with a review request. In order to start a new review request for a document, select New Review Request, and then choose (None - File attachments only) when selecting a repository.

Once you have a review request, attach a PDF file, either by dragging and dropping the file onto the browser window, or using Update ‣ Add File. This will add the file to the review request, and will be reviewable once the review request is published.

../../../_images/document-thumbnail.png

Note

Documents must be in the PDF format to be reviewable. If you have a document in another format (such as Microsoft Word), save it as a PDF before uploading it to Review Board.

Browsing a document

To open up the document review page, simply click on the thumbnail for the file attachment on the review request page. This will bring up an interface for browsing the document.

../../../_images/document-review-ui.png

This interface has several controls for browsing through the document.

At the top left is a toggle for a sidebar which can be used to browse through the document. When the sidebar is open, it can show either a list of pages or the table of contents. Not all documents contain a browsable table of contents; if a document does not, the sidebar will only contain the page list.

In the center of the top bar are controls for jumping to a specific page or moving back or forward a page.

At the top right are controls for zooming in and out of the document.

Commenting on a document

To place a new comment on part of a document, simply click and drag to select the desired area. This will pop open a new comment dialog, just like in the diff viewer.

Comments support rich text using the Markdown language. See Using Markdown for more information.

The file attachment comment dialog supports issue tracking. See the section on Issue Tracking for more information.

Once you’re done writing your comment in the text area, click Save to save the comment.

A rectangle with a green number box will appear in the region you selected to indicate that you have a comment in that area. Click the box to pop open the comment box for your existing comment again.

Reading existing comments

When your mouse cursor is over the document, regions representing other comments may appear with blue number boxes in the corner. Each of these is a comment someone has made on another review.

If you move the mouse cursor over the region, a tooltip will appear showing a summary of the comments made.

If you click on the region, the comment dialog will appear, along with a blue side panel on the left showing those existing comments. You can still write new comments in the green area of the comment box.

Note

It’s important to note that this is not the place to reply to those comments. When you add a comment from the PDF viewer, it’s creating a new top-level review (akin to a new thread). If you want to reply to existing comments, you can do so from the Reviews page. The Reply link here is a shortcut to jump directly to the relevant comment on the Reviews page.

The view here is meant to be used only as a reference to see if other people have already said what you plan to say.