Correction: Web 2.0 Sucks For Reviews

There’s an interesting phenomenon taking place lately that I find a bit disturbing. It has to do with how consumers are leveraging their newly discovered online powers of opinion. In principle, I think empowering people by given them tools to communicate with one another is a good thing – people should be able to be heard, and share ideas and comments on everything, including the products they chose to buy or not. But when it comes to software applications and services, reviewers are all to ignorant of how permanent their actions are compared to how rapidly what they’re reviewing can change.

Take for example the smackdown currently being handed to EA’s “Spore” on Amazon.com. As of this writing it has 3,000 ratings, 2,500 of which are one-star reviews filed by users upset by the copy protection software it uses. The majority of these reviews come from users who likely haven’t played the game, mind you, they are merely protesting the copy-protection system they’ve heard about. I’m not saying DRM protection is a good thing, but it does seem like the punishment here is a bit excessive. Spore is doomed to never rise much higher than “two-something star” rating no matter what EA does to improve it or address their users concerns. This would require receiving nearly 2,000 more 5-star reviews, which is over double the total number of reviews that the most popular video game ever made (World of Warcraft) has received in the four years it’s been listed on Amazon.

The first Spore review, alone, has been marked as “helpful” by over 6,500 people, most of whom are presumably deciding not to purchase the game. This in spite of the fact that the review is no longer accurate (EA revised the Spore DRM less than two weeks after the game’s release.) That’s $325,000 in lost revenue. From a single review. Ouch.

Amazon’s review system, like nearly all such systems on the web, is designed to let people review immutable things like books, CDs, or even Tuscan Milk – products that don’t change over time. But software is dynamic – it can be updated and improved, even after you bought it. And this is something that simply isn’t taken into account; not by sites that let you comment on products, or forums, or any other myriad channels we users pay attention to. What’s needed is a way to temper the relevence of reviews and comments based on how a product evolves over time. In the meantime, it would behoove people to be a little more circumspect in what they review and how they review it.

Documenting JavaScript – jGrouseDoc

Over the years, I’ve spent a lot of time searching for (and even creating) tools that do automatic documentation of JavaScript. As anyone familiar with this issue can attest to, it’s not an easy problem to solve, and the tools available seem to yield mediocre results at best.

There is, however, a new entry into the field that I’ve been using for month or so now, and that I find myself pleasantly surprised by. The tool is jGrouseDoc (jGD), by Denis Riabtchik. Unlike it’s predecessors, jGD starts with the premise that attempting to parse JavaScript source code is a futile endeavor. The language is not designed to express the high-level concepts and patterns that engineers strive to emulate (and document) in their design.

Instead, the tool looks exlcusively at the information in the comments you author, and provides a rich set of tags for you to annotate your comments with information about the logical structure. This requires a bit more typing, but frees the author and the tool from the shackles of having to figure out how to bolt documentation into the source in awkward ways.

For anyone familiar with JavaDoc, you’ll find the syntax easy to pick up. Here’s what it looks like ..

/**
 * Similar to Prototype's Template object, except the template is a DOM
 * element instead of a string.
 *
 * @class DomTemplate
 */

/** Hash of template id to DomTemplate objects
 * @variable {static Object} _byId
 */

/**
 * Get a dom template by name.  The returned template is cached, so
 * subsequent calls (for the same template) are efficient.
 *
 * @function {static DomTemplate} getTemplate
 * @param {String} id element id
 */

/**
 * Get a DOM element to use for doing DOM manipulations
 *
 * @function {private Element} _getHelper
 */

/**
 * Use DomTemplate.getTemplate()
 *
 * @constructor {private} initialize
 */

/**
 * Similar to evaluate(), except returns a DOM element. Note that for bulk
 * operations, it's more efficient to use evaluate() to create the HTML
 * string and then apply that using innerHTML.
 *
 * @function {Element} evaluateElement
 * @param {Object} data key-value pairs for token replacement
 */