The document below has a numbered blue "comment dot" () at the beginning of each paragraph and list item. To post your comment on a particular item, click the appropriate blue dot. Each item that already has comments also has a "view comments" glasses icon (); click it to see the comments on that item. You can also add a general comment or view everyone's comments:
1 by Adam C. Engst <firstname.lastname@example.org>
2 Last week I examined a number of document collaboration systems I've used and passed on some advice for setting up a system of your own. However, all the systems I talked about involved sending files - usually Microsoft Word files - via the Internet. This week I'm going to look at a couple of document collaboration systems that exist entirely on the Internet: QuickTopic and WikiWikiWebs. A few similar systems that I haven't used have also been mentioned in TidBITS Talk - be sure to check them out too.
4 QuickTopic Document Review -- The first of these services is the new QuickTopic Document Review Web site. First, QuickTopic itself is a lightweight Web-based single-topic discussion space. It's not completely private - the only security is through obscurity (the URL for your discussion contains a randomized set of letters and numbers) - but it could be useful for quick discussions. It displays messages one on top of the other on a Web page, and it can email you the messages if you prefer. It's a clever idea, but I prefer to use Eudora, which offers more flexible reading and writing environments, and archives everything for posterity.
6 I've found QuickTopic Document Review more interesting, because it provides an easy way to let any number of people read and comment on a document without worrying about file formats, file exchange, or comment conventions. All anyone needs is a Web browser.
8 Here's how it works. First, someone uploads an HTML document, and QuickTopic Document Review prefixes each paragraph and table cell with a "comment dot" and a sequentially numbered link. To make a comment, click the comment dot or numbered link, and then enter your comment in the text entry box that appears on the next page. When you submit the comment, QuickTopic creates a new discussion linked to the document and displays it. You can view comments alone or comments along with the paragraph they refer to, and you can sort comments by poster or by paragraph number, all of which can be helpful when integrating comments into your original document (which you must do manually, of course).
9 The XNSORG Communications Working Group recently tried QuickTopic Document Review for reviewing a large white paper. It worked well, though there are some rough spots. For instance, making comments and submitting them both take you to new pages, so you must either create comments in new windows or click Back twice to return to the original document. The developer of QuickTopic is constantly polishing the system, so I have high hopes for its future.
10 To get a sense of how QuickTopic Document Review works, try commenting on this article via the link below.
12 Wikis -- QuickTopic Document Review enables reviewing of documents, but what if you want multiple people to edit the same document online? For that, you can turn to another technology called a WikiWikiWeb (the term comes from the Hawaiian word for "quick" and is often abbreviated to "wiki").
13 A wiki is Web-based software that provides live document editing via the Web. In fact, a wiki enables live editing of entire Web sites, complete with automatic page creation. This level of freedom can be unsettling, accustomed as we are to the laborious process of creating, editing, uploading, and modifying Web pages. It's even more disturbing to think that anyone could edit or even delete your text. And yet, from what I can gather from reading wikis and talking to people who use them seriously, such textual vandalism seldom happens.
14 The main reason is akin to why open source works - social pressure to fit into the group. Other protection mechanisms exist as well. Every version of a wiki page is saved (efficiently, through the use of diffs that record just changes between versions) so you can always go back to a pre-vandalized version. Plus, some wikis provide IP-range and password security to individual pages so, for instance, everyone can read a page, but only some people can make changes. Another option lets only authorized people edit a page, but allows anyone to add comments to the end.
15 Another aspect of wikis that tends to throw people is that formatting is minimal. Wikis aim to promote communication, not layout. The level of formatting varies between wikis, but there are usually simple wiki-specific formatting rules (like turning lines starting with asterisks into bulleted lists, turning lines of several dashes into horizontal rules, and so on). Many wikis also support HTML markup, though most people don't bother since it's seldom worth the effort. Some wikis support graphics, but it's safe to say that most primarily contain text.
16 Using Wikis -- The original WikiWikiWeb was created by Ward Cunningham, but I've found that site's explanations overly abstract and disorganized. It's interesting to browse around in Ward's original wiki, though I'll warn you that it's easy to become brain-boggled in the process.
18 Since the wiki software itself is open source, a vast number of wiki clones have arisen, written in a wide variety of languages and running on a wide variety of platforms. Some even provide free wiki space to all comers, so you can set up your own wiki for testing or document collaboration, such as on the WikiWeb site (where they also sell wiki software for intranet use).
20 I used the WikiWeb site to collect questions for the annual Netters Dinner Survey at Macworld Expo this year. People could read the existing questions, and then either edit them (to add new answers, for instance) or add new questions. It worked relatively well for gathering a base set of questions which I used when emceeing the obligatory raise-your-hands survey. I've also set up another page on WikiWeb where I originally encouraged people from TidBITS Talk to explore and post comments - it showed me that wikis are too free-form for discussions, since comments can be added anywhere and there's no indication of when comments were made or (sometimes) who made them. Where wikis shine is creation and editing of documents, and so you can see what it would be like, I've uploaded this entire article to the WikiWeb site as well.
22 I've had more experience with XNSORG's internal wiki (we hope to open it up soon) for developing and reviewing content. Pages start in one of two ways - either essentially blank or relatively complete. For instance, we're talking about new content for our home page right now, so I created a page (page creation is merely a matter of naming the page and clicking a link) and roughed in some text. My goal is not to do all the work on the first pass myself, but to put enough material up there that others, when I send them the URL to that page, will be jogged into adding text, making changes, or perhaps just making comments. Plus, I can make changes any time I want without needing to distribute new versions. This approach can work well for starting a document no one desperately wants to create, since it spreads the workload. In this case, someone always ends up taking responsibility for the document, which entails copy editing, checking links, and tweaking the formatting.
23 At other times it makes more sense to take a mostly completed document and put it up on a wiki page for review and editing. This approach can save time for the person primarily responsible for the document, since the people reviewing often find and fix minor errors and can add or modify explanations as appropriate. This doesn't eliminate the need for the author to do the final edit pass, but it remains a flexible way to collect comments and changes without maintaining or distributing multiple versions.
24 Other uses we've found for the wiki include an easy way to publish working group meeting minutes without the effort of building and posting traditional Web pages, an open agenda to which all members of a working group can add items, "road map" documents which change frequently, and to-do lists for members of working groups. Overall, I'd say the wiki is a great success, and we're still thinking of ways to use it. For instance, once we can open it up to the public, we'd like to use it for FAQs, so people could ask questions and we could answer them, right on the same page as all the others while avoiding the slow process of revising and posting traditional HTML documents in a group setting.
25 Wiki on the Mac -- Although I found the public WikiWeb site, I wanted to see about running a wiki on a Mac. Most wikis are written in nominally cross-platform languages like Java or Perl, but I have neither the time nor the expertise to get them running on a Mac. Then I was alerted to the existence of Swiki, which was written in a Smalltalk variant called Squeak, developed initially as a research project at Apple (the developers reportedly followed Alan Kay to Disney). Swiki (I can't believe they missed naming it SqWiki, or "squeaky") requires its own Web server, called Comanche, and you can download and install the complete package for free. It wasn't hard - just follow the instructions on the second link below (since the instructions themselves are on a wiki, the one place where I found them confusing, I did some editing).
27 I haven't tested it under any strain, but it seems to work on my PowerBook G3 (other than email notification of changed pages). I've also been impressed with Swiki's feature set - although I'm by no means experienced with wikis, Swiki seems to offer significantly more features in terms of formatting and access controls than many other implementations. If you like playing with Internet servers, Swiki is definitely worth a look.
28 Although the PowerBook is a lousy server machine for the simple reason that I take it offline on occasion, I'm considering testing Swiki as a way to collaborate with authors on TidBITS article drafts. The two main drawbacks are that editing tools available in a Web browser text field are primitive at best, and we'd lose our internal color coding system if we took the text out of Nisus Writer. However, I think I can address these criticisms with a macro that uses Nisus Writer as the editing environment and translates between Nisus Writer's formatting and Swiki markup.
29 We'll see how it works, and perhaps I'll end up with an additional resource in my document collaboration tool kit for future projects. In the meantime, I hope this series has been helpful in providing ideas for your own collaboration needs, and make sure to share other approaches you've used on TidBITS Talk.
30 We've published this article on QuickTopic Document Review for testing and example purposes. For the final version of this article as published in our article database, please visit <http://db.tidbits.com/getbits.acgi?tbtxt=Swiki>