Tangled in the Threads

Jon Udell, January 24, 2001

QuickTopic Document Review

Sharing, and discussing, routine documents

Steve Yost's "preposterously easy" discussion tool now enables collaborative document review

For years I've been harping on the subject of "the writeable web" -- what the web was supposed to have been from the start, and is only now starting to become. Discussion tools, in many different flavors, are one part of the story. Another is collaborative review and discussion of documents published on the web. An early example of this mode was Ka-Ping Yee's annotation system, Crit. More recently, the weblog movement has popularized a format that invites discussion of a stream of published documents (or sometimes just annotated links).

What hasn't been solved well, until now, is the problem of helping a small group -- an author, an editor, some reviewers -- collaborate on a working draft of a document. I faced this problem while writing my book, and came up with a prototype scheme -- described in the book -- that ties a web representation of the document to a discussion forum. In my prototype, the discussion tool was an NNTP newsgroup, but as we'll see, it can be anything. The scheme was based on these ideas:

The use of an NNTP newsgroup as the discussion component made some fancy things possible -- for example, I found I could generate a complete table-of-contents-like discussion framework into the NNTP newsgroup. But although I was willing to run an NNTP server and run the scripts that made all this magic occur, the solution was hardly one that would appeal to a normal web user.

Introduction to QuickTopic

Then, last year, I took another run at the problem. The Software Carpentry Project asked me to write an essay on Internet groupware for scientific collaboration. As I reviewed how the scene had changed since I'd written my book, I was much impressed with Steve Yost's QuickTopic. Here was a tool that tackled the central problem of groupware: getting people over the activation threshold. Here's what the report says about QuickTopic:

As useful as private (that is, non-Usenet) NNTP discussions can be, they fail to meet one of the requirements for an ideal collaborative solution. Most people can't form NNTP discussion spaces on the fly, without the help of a central authority. An innovative service, http://www.QuickTopic.com/ (formerly www.TakeItOffline.com), tackles precisely this problem. It's a web/email hybrid that creates "instant discussion spaces" each focused on a single topic

To use QuickTopic you visit the site, name and describe your discussion topic, and provide your email address. The site creates a discussion space, and emails you an URL referring to it. To recruit others into the discussion, you forward them this message (or just the URL). Topics are shown in a linear style without threading, but you can create a new topic and link it to an existing one to create a branching effect.

How private are these discussions? The documentation frankly explains:

Your topic is just as private as its web address -- no more, no less. This address is extremely hard to guess. It's a randomly generated series of alphanumeric characters

This URL-is-the-password solution is fine for many kinds of casual use. More rigorous security protocols are of course possible. It would be easy to encrypt the web component of QuickTopic, though much harder to encrypt the email component while preserving the spontaneity that is a key strength of the system.

QuickTopic was designed not to replace the mailing list, but to augment it. Mailing lists, newsgroups, and web forums are best suited for long-term collaboration. These solutions tend to be too heavy, and too static, for the kinds of ad-hoc, short-lived interactions that characterize so much of our real collaborative work. In these situations we invariably use email, despite its limitations, because it comes easily to hand. Like the single-topic bulletin board associated with a TimeDance event, a QuickTopic instant discussion is ad-hoc, lightweight and disposable, yet more focused, more centralized, and more accessible than a mailing list.

My QuickTopic document-review hack

Naturally I wanted my online report to accept reader comments. I realized that QuickTopic could replace the NNTP component in my original scheme. Soon, thanks to the astonishing flexibility of the web, I had a solution. The report includes this chunk of JavaScript: 

function postComment ( elt, quote )
  {
  reviewScript = 'http://software-carpentry.codesourcery.com/GroupwareComment';
  tioTopic = 'http://www.quicktopic.com/3/H/QBy8VC7YGoSGbu4q71/';
  win = window.open ("", "commentWindow", "resizable=yes,width=600,height=500");
  win.document.open ( "text/html" );
  with ( win.document )
    {
    writeln ( '<html><head><title>Comments on "Internet Groupware for 
        Scientific Collaboration"</title></head><body>' );
    writeln ( '<p><b>Comments on "Internet Groupware for 
        Scientific Collaboration"</b></p>' );
    writeln ( '<p>Use this form to comment specifically on paragraph ' + elt + ':');
    writeln ( '<blockquote><i>' + quote + '</i></blockquote>' );
    writeln ( 'Your comment will be posted to a discussion space, and 
        linked to this element. Alternatively, for general discussion 
        of the document, you can <a href="' + tioTopic + '" target="discussion">
        go to the discussion</a>.</p>' );
    writeln ( '<form action="' + reviewScript + '" method="post">' );
    writeln ( '<input type="hidden" name="element" value="' + elt + '">' );
    writeln ( '<b>Your name</b>: <input name="who">' );
    writeln ( '<textarea name="comment" rows="12" cols="50" 
        wrap="virtual"></textarea>' );
    writeln ( '<br><input type="submit" value="post comment">');
    writeln ( '</form></body></html>' );
    }
  }

In the document, every paragraph and list element has this format: 

<li><a name="17">
<p>
are made of standard components 
<a href="javascript:postComment(17,'are made of standard  ...');">
<font size="-2" color="green">17</font></a>
</p>
</li>

The <a name="nn"> that precedes the paragraph is the destination for the backlink from the comment, once it's posted. The JavaScript call that follows the paragraph gives the postComment function what it needs: an element number, and a leading fragment to quote for context.

On the back end, since this document was hosted on a Zope server, I used a Python method to handle the comment form and plug the comment into the discussion using the QuickTopic web API: 

def screview(self,REQUEST,RESPONSE):
    import urllib
    reportURL = "http://software-carpentry.codesourcery.com/Groupware/report.html"
    topic = "QBy8VC7YGoSGbu4q71"
    subj = "Groupware+Report"
    element = REQUEST['element']
    who = urllib.quote(str(REQUEST['who']))
    comment = urllib.quote(str("in reference to: " + reportURL + 
       "#" + element + "\n\n" + REQUEST['comment']))
    url =  "http://www.takeitoffline.com/cgi-bin/post.cgi?action=postreply&
       forum=3&topic=" + topic + "&TopicSubject=" + subj + "&UserName=" + 
       who + "&ReplyMessage=" + comment
    return REQUEST.RESPONSE.redirect(url)

This worked pretty well. The report attracted a reasonably lively discussion, and that discussion integrated with the document's granular namespace just as I envisioned it should.

But the whole thing was still an order of magnitude too geeky for general use. A normal person is not going to want to process a document to embed the necessary instrumentation -- the JavaScript function, and the comment links. Nor is a normal person going to want to supply a Python method, or CGI script, or whatever else may be needed to connect the comment form to the discussion by way of QuickTopic's API.

Then there's the question of format. I'm in the habit, nowadays, of writing in XHTML. This makes sense for me since most everything I write goes to the web, and I often want to postprocess documents to achieve various effects. But, this is a distinctly geeky habit I admit.

Well, I'm delighted to report that Steve Yost has now solved these problems with a new feature, QuickTopic Document Review.

It's official: QuickTopic Document Review

Steve has always had an instinctive grasp of the KISS (Keep It Simple, Stupid) principle. He's not kidding when he calls QuickTopic a "preposterously easy instant discussion space." It's really hard to get people over the groupware activation threshold. Registration is one major hurdle, so QuickTopic doesn't require it. This alone is a huge benefit. I've used a QuickTopic discussion to collect feedback on a beta version of a web-based product, and it worked extremely well for this purpose because it was effortless for me to create the discussion and link the product to it, and nearly as effortless for people to use the discussion.

QuickTopic Document Review is equally simple. Ideally, the documents that you upload should be well-structured XML. But Steve's a relentlessly practical guy, and he understands that requirement would leave most people by the wayside. So, he accepts any old HTML. In particular, he invites you to save MS Word docs as HTML and upload those. This should enable vast numbers of ordinary business documents to enjoy the benefits of web-based collaborative review. Because end tags are not guaranteed to be available in HTML, it wasn't possible to attach comment links to the end of every paragraph and list element. Instead they attach to the beginning of each element. But so what? It's consistent, it's easy to understand, and it's good enough for the purpose.

I'm really excited by this new QuickTopic capability. Because your document-based discussion is a normal QuickTopic discussion, all the usual features are available. You can edit the most recent comment, sort by author and date, subscribe for email delivery of comments, and count the number of pageviews and readers. For document review, Steve's added a number of nice touches:

QuickTopic Document Review is designed to make it easy for anybody to have a web-based collaboration focused on an ordinary document. I think it achieves that goal admirably, and brings us a major step closer to a world in which this kind of collaboration is simply routine. Nice work, Steve!

Jon Udell (http://udell.roninhouse.com/) was BYTE Magazine's executive editor for new media, the architect of the original www.byte.com, and author of BYTE's Web Project column. He's now an independent Web/Internet consultant, and is the author of Practical Internet Groupware, from O'Reilly and Associates. His recent BYTE.com columns are archived at http://www.byte.com/index/threads

Creative Commons License
This work is licensed under a Creative Commons License.