The Elegance of Bracket Notation

December 21, 2008

What’s the best way to annotate an electronic document with revision notes and comments? Mainstream word-processing products include revision tools, but they’re complex and only work in the context of this or that piece of software.

It turns out that the simplest thing that could possibly work also works in all text-editing situations: bracket notation. I first read about bracket notation in an article on the Humanized blog and thought it quite clever. So, when a friend recently called on me to make some revisions to a letter he’d sent me via email, bracket notation came to mind and fit the bill perfectly.

Not entirely satisfied with the Humanized system, I invented my own derived form. The general formula is as follows:

([old text] [new text] [notes/reviser])

The third bracket, containing any notes or the reviser’s name, is optional.

To demonstrate bracket notation in action, I’ve provided a sample below. The text comes from a slightly modified (for demonstration) passage from Strunk and White.

Draft

The most powerful writing is concise. A sentence should not contain any unnecessary words; a paragraph no unnnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine should have no unnecessary parts.

With Bracket Notation

([The most powerful] [Vigorous]) writing is concise. A sentence should ([not contain any] [contain no]) unnecessary words([;] [,]) a paragraph no ([unnecessary] [unnecessary]) sentences, for the same reason that a drawing should have no unnecessary lines and a machine ([should have no] []) unnecessary parts ([Well said!]).

Revised

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts.

Design-Build Development

October 05, 2008

Explanations of Behavior-Driven Development often contain much nuance and noise. This FAQ is an attempt to provide a straightforward account of BDD, especially for beginning practitioners and those who have never quite understood it. To do so, this article tries to work around the three biggest obstacles to understanding Behavior-Driven Development: the main emphasis, the word “test,” and the word “behavior” itself.  (more...)

Shoulda Testing Cheat Sheet

September 12, 2008

Updated 10/1/08: Modified for the release of Shoulda 2.0.

Updated 9/26/08: Fixed some typos and omissions. Added should_route and should_render_with_layout (Thanks to Dan Croak and Michal Szajbe).

I’ve created a basic Shoulda cheat sheet. Along with Topfunky’s "Ruby on Rails Testing Cheat Sheet":http://nubyonrails.com/articles/ruby-rails-test-rails-cheat-sheet, it should be a good reference, especially for those migrating from RSpec.

Uniting

August 17, 2008

Engineers and designers must collaborate. Whether building a bridge, a commercial jet, or a web application, the most elegant solution will result from an open dialog between design and engineering. Apple understands this. So does Boeing, with its notion of the design/build team. This sort of cooperation will always be important. Big Contrarian recently wrote about the fallacy of thinking otherwise:  (more...)

From RSpec to Shoulda

August 13, 2008

Shoulda

What’s the best Rails testing framework? The one that makes your testing life most enjoyable, of course. For me, this has been RSpec, but I’m beginning to prefer Shoulda.  (more...)