Sometimes the solution to an interface problem doesn't involve inventing something brand new, just reusing something old.

Friday
30 Jun 2006

Collaboration Made Simple with Bracket Notation

Life Hack

I just had the dubious honor of writing my first patent. It was a laborious and arduous process that I would only force on my best enemies. Luckily I had help from my coworkers. But help meant collaboration, and collaboration meant too many hands in the cookie jar. Edits flew like popcorn kernels on the griddle. It was the stuff project manager nightmares are made of and we needed a robust method of keeping track of comments and edits to combat it.

When writing, I like to keep things simple. And while I don’t go to the extremes of Khoi Vinh’s Blockwriter, I use an editor that can’t even make text bold. When I write, it’s just the raw text and me, mano a mano. By using a bare-bones editor, the text can’t fight dirty by throwing frivolous fonts and formats in my eyes.

Everyone at Humanized writes the same way, so how did we collaboratively write and revise the patent? We couldn’t just edit, because in a patent every change is crucial and must be reviewed. We couldn’t just use standard revision control, because we needed to shoot things back-and-forth across myriad different file formats (we all use different editors). We needed another solution. We needed an elegant solution.

In the end, we found our solution in the personal trick bag of Jef Raskin, the master of keeping simple things simple. He didn’t have a name for it, so we dubbed it “bracket notation”.

It’s simply three sets of square brackets. The first set denotes deletion, the second set denotes addition, and the third set denotes a comment. It’s easiest to explain by example. Let’s start with a simple sentence plagued by two typical errors:

They called to say that their coming over in an quarter-hour.

An editor might revise the sentence to:

They called to say that the[ir][y’re] coming over in a[n] quarter-hour. [][][Be careful with “their” and “they’re”.]

The edits are deciphered like so:

  • the[ir][y’re]: “their” was used when “they’re” was meant. To fix this problem the editor suggestions deleting “ir” and replacing it with “y’re”.
  • a[n]: “An” should only used before a word that begins with a vowel-like sound. The editor suggests removing the “n” of “an”.
  • [][][Be careful…]: The editor is reprimanding the author for forgetting the rules of English. Notice the two sets of empty brackets that prefix the comment. They are needed to make sure that comment cannot be confused for an addition or deletion.

After you use braket notation for even a little bit, the order of the brackets will become second nature. But, if you need a mnemonic, just remember that a number line always goes from negative to positive. The same is true of the markup, it starts with subtraction and goes to addition. Now let’s try a sentence in drastic need of some complex editorial help,

The silver quick-browed fox jum over thier lazy dog.

This might be edited as so:

The [silver] quick[-][ ]brow[ed][n] fox jum[][ped] over th[ier][eir][Remember, I before E, unless after C. Unless the word is weird.] lazy dog. [][][Shouldn’t “their” really be “the”?]

This looks a bit scary at the outset (the density of comments is pretty high), but it is easy to follow the edits:

  • [silver]: Delete “silver”.
  • [-][ ]: Delete the hyphen and add a space. Notice how easy it was to show changes dealing even with white space.
  • brow[ed][n]: Delete the “ed” and add a “n”, resulting in “brown”.
  • jum[][ped]: Don’t delete anything and add “ped”, resulting in “jumped”.
  • [ier][eir][Remember …]: Delete “ier” and add “eir”, resulting in “their”. The editor has included a somewhat ironic comment about the inconsistency of English spelling.
  • [][][Shouldn’t …]: Like in the first example, this is simply a comment.

Thus, if all changes were accepted, the edited sentence would be:

The quick brown fox jumped over the lazy dog.

The bracket notation method is never ambiguous, easily readable, and can be used with reckless abandon in email. To find changes. you just search for an open square bracket, accepting and rejecting comments is as simple as selecting and deleting text. Having been recently forced to used Word’s revision system, it is a true joy to come back to this elegant markup. It just works.

I mentioned earlier that bracket notation can be used for collaborative editing among many editors. So how do you know who has made what comment? Adding an author tag is easily accomplished by putting meta data in the comment section. For instance, “If it’s not chocolate, it’s not dessert” might be edited to:

If it[’][][”It’s” does not equal “its”! -Jono 7/4/05]s not chocolate, it[’]s not des[s][][-Aza]ert.

In this way, adding any meta data about the edit is easily written, searched for, and read.

The only thing lacking is some simple syntax highlighting. It would be great if color could make the comments jump out at me to give that slight edge in readability. The problem is that the syntax color-er would have to be available anywhere on my computer so that I could use bracket notation in its full glory, whether it be in Gmail, Word, or Emacs. Nothing currently exists that makes that possible. Yet. Check back at the Humanized site in August.

So give bracket notation a try the next time you need to edit something. You might be pleasantly surprised at just how seamlessly it works. We’ve been using it for a long time, and we like it. It’s a simple solution to a possibly complex problem. It shows that sometimes the solution to an interface problem doesn’t involve inventing something brand new, but reusing something old.

by Aza Raskin