Review everything, not just code

Code review is a staple in many engineering cultures. The benefits to putting your code up for your teammates to scrutinize and critique are numerous. There’s the satisfaction of showing off your work to your peers and the comfort in knowing that any obvious flaws or bad design choices will be caught before they affect others.

Unfortunately, code review is often where thorough review ends for many teams. UI changes, mockups, PRDs, documentation, release notes, icons, and other visual components critical to a project are not always as closely inspected, or at least are not done so as part of the existing code review process. By leaving these out, or doing them out-of-band (e-mail, in-person reviews), or even by going through entirely separate tools, there’s the risk of missing and tracking valuable feedback.

Through Review Board and Power Pack, you can review those just as easily as code. No new tools to learn, no loosely tracked discussions. Here’s how.

File attachments on Review Board

In Review Board, you can attach any type of file to a review request and review.

There’s built-in support for general text-based file attachments, Markdown files, and images. Extensions can supplement that with support for reviewing additional file types, like PDF. Unsupported binary files can still be reviewed by downloading the file and then leaving a comment on it.

All you need to do to attach files is to drag them (as many or as few as you want) from your file manager right onto any new or existing review request.

Or, if you’re a command line junkie like I am, check out tip #3 on our 5 tips for RBTools.

You’ll be able to try these yourself on our demo page.

Reviewing screenshots, icons, and other images

If you’re developing a UI for your application, make sure your fellow engineers or your usability team sees it before your QA team or users do.

Take a screenshot, or two, or a dozen. Show off all the changes you made, the new dialogs, the icon updates. Upload them as part of your code change so that your reviewers can see the impact of your code. Your reviewers will then be able to go through your screenshots and review them just like source code.

Reviewing images is easy. Simply click-and-drag over an area of the image, like you’re selecting it. A comment window will pop up (just like for code). Enter some text and save it. When the review is published, you’ll see that section of the image in the review, and discussion can begin.

Image Review

Reviewing plain text files

As developers, we love plain text. We have one-off bits of test code not fit for the tree, we have log files, development notes, test runs. All kinds of things that your reviewers may find useful when looking at your code.

So post them.

Reviewers will see a nice display of the text similar to what they’d see in the diff viewer. If Review Board recognizes the file type, it’ll even syntax highlight it for you, which is great for files like XML.

Text Review

Reviewing Markdown files

Markdown is a pretty popular way to write rich, formatted text in the comfort of your 1970s text editor. I’m using it right now to write this post, in fact, and you may be using it for your documentation or Wiki pages.

During review, we automatically render your Markdown so that you can see how it looks. Reviewers can leave comments right on the rendered copy or on the raw Markdown text.

Want to see this in action? Check out our demo.

Markdown Review

Reviewing PDFs or other documents

Product managers and doc writers generally aren’t writing Markdown or code. They’re working in Word, Excel, Power Point, or something more specialized. When they want a review of the latest PRD or section of the manual, they probably just e-mail it out to you, and you probably e-mail them back some replies. Yuck.

Instead, convince management and your doc writers to export their documents as PDF, and then upload them to Review Board. If you have Power Pack installed, or you’re an RBCommons subscriber on a Medium plan or higher, you’ll be able to read through the PDF and comment on any part of it.

This works very similarly to screenshot commenting. Click-and-drag to select a region, and leave a comment. That section will appear along with your comment in the review, just like with code or screenshots.

It’s a much better way of tracking all the feedback around the design or documentation of your product.

You can see what PDF review is like over on our demo page.

PDF Document Review

So in conclusion…

Review all the things!

Read More

New Beta Release: Review Board Power Pack

Review Board Power Pack

Until now, we’ve been running two separate beta programs for PDF Review and “Review Board Enterprise”. We’ve decided to merge these together into a single product that we’re calling the “Review Board Power Pack.”

The major features of the combined package are:

  • Review PDF documents that are attached to review requests, commenting directly on the text, all in the browser with no extra plug-ins.
  • GitHub Enterprise support.
  • The ability to add capacity to your Review Board server by adding additional front-end servers.

Changes in the new preview

In addition to merging together the features of our two previous beta packages, there are some improvements and bug fixes for PDF Review in this release:

  • The outline mode in the sidebar now shows the tree structure of the table of contents.
  • When a document has a table of contents, the sidebar now allows switching between either the outline mode or the pages mode.
  • Scrolling behavior when using the mouse wheel or touch-pad gestures has improved significantly, making it easier to get all the way to the bottom of the document.
  • Non-PDF documents like .docx are no longer detected as PDF.
  • When attaching a PDF file with drag-and-drop, you can now click on the thumbnail to jump to the review UI to preview the document.
  • Several issues with PDF rendering have been fixed.
  • A fair amount of visual design polish.

pdf

Getting the Power Pack

If you already signed up for the beta, you should have an email explaining how to install it (or upgrade from the first beta). If you haven’t signed up, but would like to participate, please fill out our sign-up form and we’ll be in touch.

Once we have a final release, these features will be available on RBCommons.com for our larger tiers.

Read More

PDF Review Beta 2

A few weeks ago, we did our first private beta release for an extension for collaborative peer review of PDF documents. If you haven’t seen it yet, we encourage you to check out the original announcement, which explains the basic workflow.

Since that first release, we’ve received a lot of great feedback, and have been working hard to improve it. We’re proud to announce a new beta release, with several significant improvements:

  • Continuous scroll through the document!
  • Significant performance improvements when switching between pages.
  • Review emails now contain the selected sections for each comment.
  • Comments on the “Reviews” page and in review emails now link to the relevant page in the document.
  • Improved interaction when dragging out comment areas.
  • Improved visual layout, maximizing the amount of space for the document.
  • Fixed an issue where the page would continually make requests to the server when thumbnail storage fails (for example, if the PIL version on the server can’t handle PNG compression).

pdf-continuous-scroll

If you already signed up for the beta, you should have an email explaining how to install it (or upgrade from the first beta). If you haven’t signed up, but would like to participate, please fill out our sign-up form and we’ll be in touch.

Read More

PDF Review Beta

A little while ago, we announced that we were building document review features for Review Board. This will be available as a commercial extension in order to help fund the project. Of course, once it’s ready, RBCommons customers will get it as part of their normal plans. I’d like to show off a bit what you’ll be able to expect.

Since Review Board 1.6, you’ve been able to attach arbitrary files to review requests. For anything except images, the only way to view them was to download them. You could add general comments to these files, but for large things like a document, you couldn’t use the direct commenting that we’ve all come to love from the diff viewer.

With the PDF Review extension, when you upload a PDF file, it gets a thumbnail and a “Review” link.

review-request

Clicking on this file will open up the PDF Review UI, which has controls to navigate the document. The file is rendered directly in the browser with no plugins (which requires a relatively modern browser).

pdf-viewer

Like image review (and screenshots before it), you can add a comment to the document by clicking and dragging over the area that you’d like to talk about.

adding-a-comment

When you publish, the areas that you selected will be copied into the review along with the page number on which they occurred.

review

If you signed up for the beta program already, you should have received an email with instructions on how to install and activate this extension. If not, feel free to sign up and we’ll get in touch!

Read More