Shared annotations?

Volume 10, Issue 92; 18 Sep 2007; last modified 08 Oct 2010

Perhaps I'm responsible for reviewing more documents than the average engineer (though I sort of doubt it), but I can't believe that I'm the only one who's been waiting years for a practical way to share annotations.

My day job involves two manifestly difficult tasks: writing code to make machines do the right thing and writing (or helping colleagues write) words to make humans understand and agree what constitutes the right thing. While both of these tasks are hard, one is vastly more difficult than the other. If you haven't done both, perhaps it's not obvious on the surface which one that is, so here's a hint: it isn't writing the code.

One of the key responsibilities of a participant in a working group, or other design committee challenged to produce a specification, is to review documents: documents produced by the group, related documents produced by other groups, documents produced for implementors, documents produced for users, an endless series of documents that are attempting to describe something novel in crisp, precise prose that's not amenable to misinterpretation.

I can't imagine what this task was like before the web. I know it was successfully accomplished with spiral bound notebooks and pencils (and quill pens and parchment, come to that), but I think not on the scale or at the pace we accept as normal today. The web allows us to write and publish documents to a globally distributed network of reviewers effectively instantaneously and at will.

So, given that there are dozens of reviewers for every editor, and given that the task of review is absolutely critical to the success of an endeavour into which individuals and organizations are willing, sometimes anxious, to sink countless man years of effort and arbitrary amounts of money, why does the state of the art in document review suck so badly?

The state of the art? Here it is:

In paragraph 3 of section 2.5 of someURI dated 13 Sep 2007, where you say:

“You may not attempt to open the jeweled egg, only the thief can do that.”

do you mean “may not” in the RFC 2119 sense? If so, shouldn't that really be “must not”? If you don't mean it in the RFC 2119 sense, I suggest not using the phrase “may not”.

Bah, humbug!

For a specification that I've printed out on dead trees and carried to the beach to review with a red pen and a rum punch (not, I'll admit, the environment most condusive to technical review, but one that's sometimes remarkably good for one's sanity), I accept that transcribing comments may be the best we can do.

But not if I'm reading the document online. Surely!?

On my shiny new Mac, there's a PDF viewer called Skim that includes an annotation facility. It seems to work reasonably well, but application-specific, even platform-specific, solutions aren't acceptable. One of the benefits of annotation is that the annotations appear in context. So, while Skim can export the annotations, the exported results are stripped of context which makes them effectively useless.

A quick web search reveals a number of “web 2.0 start-up” flavored solutions. I tried a couple and they seem to work reasonably well, provided that you're online. But sitting here in my hotel room, unwilling to shell out £15 for net access, they're all inaccessible. Besides which, I'd have deep reservations about handing all this valuable data to a company that could vanish and take it all away. Review comments are often, but not always, transitory and even when they are, ideally the should become part of the permanent record of the working group.

There's at least one browser plugin in this space, but I haven't tried it yet. I suppose I could live with a Firefox-only solution, but it wouldn't be my first choice. And there's Annotea, but I haven't heard much from that project recently.

What I'd like to see is a solution that allows me to write annotations on a web document, even when I'm offline, and stores those annotations in some form that I can share with others. I don't expect the sharing part to be completely automatic, but it does have to work on a vanilla web server (no web application framework, no application server, no SQL database). I'm thinking the original document, a JavaScript library, hopefully not too big, and an XML file or two.

Anyone know of such a beast, or have I overlooked some other solution?


Tiddlywiki contains most of the pieces you look for, though it is not oriented to annotation, but rather edition.

A wiki in one html page, all javascript and styling needed. It just needs a place to POST the page after edition, and I guess turning off its "all editable" character is reasonably easy.

—Posted by Santiago Gala on 18 Sep 2007 @ 11:03 UTC #

Sit tight. Lots of those "web 2.0" providers are working on offline support. I don't have any inside knowledge, but I assume this will take the form of a specialized Web server, probably on some random port, as it will have to work on Windows as well, where you can't reasonably expect Apache or the like.

—Posted by John Cowan on 18 Sep 2007 @ 11:55 UTC #

Annotea is an RDF solution to annotation of web documents and there's a firefox plugin (Annozilla) that supports creating and sharing annotations. I can't recall whether they are stored locally but the Annotea standard defines a protocol which is pretty simple and could be implemented on a local RDF store.

—Posted by Steve Cassidy on 18 Sep 2007 @ 12:19 UTC #

Take a look at this Norm. It's for annotating HTML documents, but a nice UI.

—Posted by Bruce on 18 Sep 2007 @ 01:17 UTC #

I wrote a system inspired by Jack Sloccum's (the one Bruce links to above) for the book I'm working on. It's not exactly what you're looking for, but if you're interested drop me a line and I'd be glad to share the code and talk about how it works.

You also might be interested in the annotation system for the GPLv3 drafts. Unlike Jack's and mine it allows comments on arbitrary ranges of text. I think it feels a bit clunky, but it works pretty well.

—Posted by Jacob Kaplan-Moss on 18 Sep 2007 @ 03:10 UTC #

The Firefox addon Scrapbook kinda sorta fits. It's got the annotations and offline aspects down. I use subversion to maintain scrapbooks across multiple machines but it would be a bit clunky to share scrapbooks among groups this way.

—Posted by stand on 18 Sep 2007 @ 03:32 UTC #

maybe stickis is something for you? i have been pondering this question for a looooooong time (the time i wrote about this was in January 2000) and i guess (or maybe i just hope) now that atom/app is out, this would be the ideal platform for interacting with an annotation server. most solutions (like stickis) suffer from centralized architectures, annotea included. i'd like to see a decentralized architecture, so that i could subscribe to various annotation servers, if i feel like it.

i think that an atom/app-based solution using a better XLink (i am finally convinced that XLink has just too many fundamental design flaws to be worth to be fixed) is the solution, we'll whether this will happen. add google gears, and things are getting interesting...

—Posted by dret on 18 Sep 2007 @ 06:34 UTC #

Annotea does cover much of the problem reasonably well, and isn't difficult to hack against (a long while back I did some stuff on it with rather unlikely MSXML). Sticking it on a local server might be a decent holding pattern. But it certainly is in need of updating - and while you're at it, you might want to look at revising XPointer...

—Posted by Danny on 19 Sep 2007 @ 10:13 UTC #

this might be interesting.

I havent used it myself though.

gl, Jim Fuller

—Posted by JIm Fuller on 19 Sep 2007 @ 01:17 UTC #

You might be interested in Textensor Notate - it'll let you do the online part of group annotation / discussion of web pages and uploaded documents without installing any plugins (on IE7 or Firefox) there's a sandbox to play with it without setting up an account ... currently it's in beta, we'll think about how we might make the next version work offline too.

—Posted by Fred Howell on 23 Sep 2007 @ 08:18 UTC #

Norm, please write a piece if you find a solution that's acceptable for you; I think I mostly share your requierements and constraints but it's not pressing enough for me to go and check out all the links that your commenters suggest. 8-)

—Posted by Jacek on 27 Sep 2007 @ 12:20 UTC #

The first commenter mentioned Tiddlywiki as a good solution. People have actually been using it (and similar tools) for in-house review and collaboration on projects. Reviews are mixed and depend partly on strength of implementation and partly on the mix of features required and/or absent in a particular situation.

TiddlyWiki does not do annotation. Especially not of an external, local/network file or a webpage. It is ideally poised to take advantage of annotation technology, but nothing is being developed that I know of.

It seems a shame that either demand for a good annotation and collaboration method is so weak, or the technology just isn't ready.

I've sensed the same need you write about, and I'll be checking out the links for something I can puppet with TiddlyWiki through an iframe window.



—Posted by Coby Ingram on 18 Nov 2007 @ 10:24 UTC #

Marginalia is an open source Javascript web annotation system that allows users of web applications to highlight text and write margin notes. Marginalia has been integrated into several web applications.

—Posted by Jean Jordaan on 29 Nov 2007 @ 06:05 UTC #

Following up on Fred's earlier comment, we've just released a.nnotate which is aimed at exactly this problem (it still doesn't work off-line though). All the annotations that have been made are available as JSON (could be XML if anyone is interested) though putting them back in the right place on a PDF is not always trivial. The downloadable read-only version of document+annotations will be out with the next version. There is a free trial, and if anyone has further ideas about exactly what is needed in this space, do get in touch!


—Posted by Robert Cannon on 14 Apr 2008 @ 03:12 UTC #