Skip to content

Review Commenting Usability and URL Redirects

Jump to bottom Edit New page
EldonReturn edited this page May 12, 2011 · 7 revisions

Table of Contents

Usability Problems

When a user (the "reviewer) receives a review invitation email for a mockup posted at Maqetta.org, almost certainly the reviewer will get lost and not find his way to Maqetta's review UI. To illustrate how a reviewer can get lost, here is a typical flow of events using Preview 1. (Note: usually, a reviewer either has never heard of Maqetta or has not signed up yet at Maqetta.org)

  1. Reviewer (reviewer@example.com) receives email with a review invitation, sent by someone who has authored a UI mockup (author@example.com)
  2. Reviewer clicks on the hyperlink in the email (e.g., http://maqetta.org:55555/maqetta/review/author@example.com). (Remember this URL - it is needed several steps down below)
  3. The Maqetta application sees if the reviewer has a currently active session at Maqetta.org. For a new user, of course, there will not be an active session. The Maqetta application will then redirect to the Maqetta.org login page (http://maqetta.org/index.php?option=com_user&view=login)
  4. Assuming the reviewer is not yet registered, this page will likely confuse the user at least momentarily as he sees that he is being asked to login. Some reviewers might give up at this point, but determined users will probably figure out that they need to Register (or Sign Up - Maqetta.org uses different terms for the same action), and will click on the "Register" or "Sign Up" links on the Web site, which takes them to the Registration page (http://maqetta.org/index.php?option=com_user&view=register).
  5. The reviewer then fills out the registration form and clicks Register. This causes an activation email to be sent to his email address (reviewer@example.com), and he is redirected to the Maqetta.org home page with a message saying "An activation email has been sent..."
  6. The reviewer goes to his email client, finds an email titled "Account Details for ... at Maqetta", opens that email, and then clicks on the hyperlink that activates his account, which takes him to a page that says "You account has been activated ... you can now login to the system".
  7. If the user has gotten this far, he probably can find the "Login" link at the top right (as reviewer@example.com). The user clicks on that link and (for a second time) is taken to the Maqetta.org login page (http://maqetta.org/index.php?option=com_user&view=login). The user enters his email address and password and clicks on the Login button, which opens up the Maqetta application in normal page editing mode. 'Once again, the reviewer will be totally confused at this point. Instead of taking him to the reviewer UI, he is seeing the page editor UI.
  8. Perhaps at this point the reviewer talks to the author, and perhaps the author will have figured out that the user needs to copy/paste the URL sent a LONG TIME AGO in the original review invitation email (go all the way back to the first steps in this long story) such as http://maqetta.org:55555/maqetta/review/author@example.com. At this point, Maqetta's reviewer UI appears.

Proposed fixes to address the most egregious usability problems

  1. Assuming the reviewer is reviewer@example.com, the mail invitation should include URL parameters that provide both the initial starting "maqmode" for the application along with author and reviewer emails (e.g., http://maqetta.org:55555/maqetta/?maqmode=review&maqauthor=author@example.com&maquser=reviewer@example.com). These URL parameters will then get passed through various subsequent steps in the process.
  2. The Maqetta application running at Maqetta.org redirects to a new PHP page (e.g., http://maqetta.org/userNotLoggedIn.php?maqmode=review&maqauthor=author@example.com&maquser=reviewer@example.com). This page will immediately do a redirect to a different page. If reviewer@example.com is not yet registered, then redirect to http://maqetta.org/index.php?option=com_user&view=register?maqmode=review&maqauthor=author@example.com&maquser=reviewer@example.com; else if already registered, then redirect to http://maqetta.org/index.php?option=com_user&view=login?maqmode=review&maqauthor=author@example.com&maquser=reviewer@example.com.
  3. The registration page will add URL parameters maqmode=review&maqauthor=author@example.com&maquser=reviewer@example.com to the activation page link.
  4. We add a button to the activation page link that says "Click here to launch the Maqetta application". This page will look at the URL parameters. If maqmode=review, then launch the reviewer UI.
  • WEV - Here's something to consider: if authors were presented with a (filterable) list of registered users to invite to review versus the whole world all the registration steps go away. What's left is redirecting correctly on login. Does that unreasonably restrict or reduce the usefulness of review and commenting?
  • JF - Interesting line of thinking. I expect that some sites (particularly intranet ones) will only allow registered users to receive an invitation. In fact, in this case, there might be no registration step at all. If you are on the LDAP, you can receive an invitation. In other scenarios, particularly public ones, people might want to just type a buddy's email address and let the site (e.g., Maqetta.org) guide them through the registration and login process. I also expect there are "mixed" scenarios (particularly extranet ones) where you might have a mixture of same-company colleagues along with trusted 3rd party colleagues from partner organizations. In such an extranet scenario, sites might want to turn off self-registration and only allow registration for people who have been explicitly (white-)listed.
  • HGY (Eldon) - The reviewer still needs to perform the login action even with the "already registered" restriction. So it's inevitable that maqetta server holds a redirect url. A simple way is just to record the whole URL (http://maqetta.org:55555/maqetta/review/author@example.com) and then redirect to this url when the reviewer logs in.

Others usability fixes to consider

JUST SOME IDEAS TO CONSIDER. NOT SURE THESE ARE GOOD IDEAS.

  • I'm not sure it's better to have a whole different application for reviewing vs page editing. It might be better to merge the UIs together and treat the review board as just another editor that can be opened from the Maqetta Designer application (which supports 2 editors today: page editor and theme editor). Therefore, in the Maqetta Designer application, users could open either the page editor, the theme editor or the "review editor". When a "review editor" is active, we could make certain palettes appear/disappear and move palettes around to match what we see in the review board today.
    • Note: we already have a different file extension for reviews (file1.html.rev)
    • As Wayne reminds us, we already have had discussions about unifying author-time sticky notes with review-time annotations. If we merge reviewing into page editor, this stickynote/annotation unification might be easier from both a UI and implementation perspective.
    • If we make reviewing more integrated with the core Maqetta page designer, then down the road we could offer reviewers the ability to "clone a project" where the reviewer could create a new Maqetta project out of the files that were submitted for review, and then make UI changes within his clone. In some team settings, this would be a valuable feature.
    • If we integrated the reviewer UI into the page designer UI, then we would likely need to change the URL params described earlier. For example, we might have URL parameters something like this (leaving off URL encoding of punctuation chars): ?maqfile=Sample1.html.rev&maqauthor=author@example.com&maquser=reviewer@example.com
  • Originally, we had wanted to avoid palette proliferation, and instead of having a "Review" palette, we would integrate the review palette into the "Files" palette, perhaps renaming it to "Workspace" or "Explorer". If so then the new Workspace explorer might be a Tree control that looks something like this:
[-] Files
       Sample1.html
       etc.
[+] Reviews initiated by me
[+] Reviews initiated by others
  • When opening a *.rev file, it would help new users if we popped up a dialog that suggesting that the user go through a Reviewer Tutorial or video to introduce how the reviewer features work in Maqetta.

Extension points for generality beyond Maqetta.org

Some of the proposed steps above apply only to the Maqetta application when hosted at Maqetta.org. We need to make sure we create and document extension points so that it is straightforward to achieve the same smooth workflows when Maqetta is hosted on other servers.

My guess is that most of the effort would be around creating a sample OSGi project with associate documentation that shows a developer how to create a site-specific OSGi plugin that provides URLs that the core Maqetta application should invoke for particular services (e.g., login, logout, send review invitation, etc.) and when appropriate includes the URL parameters (maqfile, maqauthor, maquser) on any redirects.

Add a custom footer
Add a custom sidebar

Clone this wiki locally