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. This will add the file to the review request, and will be reviewable once the review request is published.
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.
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.
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.
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.