This article originally appeared in TidBITS on 2001-03-05 at 12:00 p.m.
The permanent URL for this article is: http://tidbits.com/article/6327
Include images: Off

Come Together: Document Collaboration, Part 1

by Adam C. Engst

One of the great features of the Internet, according to the pundits, is how wonderfully it enables communication and collaboration between widely separated individuals. Much of this communication occurs via email or, in some cases, via instant messaging, and works well. But I'll bet that if you've ever tried to collaborate with a group of people on the Internet to write and edit a document, you've found that moving the document back and forth across the Internet is merely a minor aspect of the entire process, and that effectively collaborating with people is quite difficult.

Here at TidBITS, we spend a lot of time together editing documents - even though none of us share a physical office - and we've worked out a system that has proven quite efficient for us. But since we all write for a variety of other publications and organizations, we've also come across numerous other collaboration approaches. It's continually astonishing to us just how hard it is to put together a good document collaboration strategy and how different groups have chosen to handle the problem.

This week I'll look at some of the major variables involved in any document collaboration system and give you a detailed look at exactly how we share documents within TidBITS. In the next installment, I'll explore a number of other systems I've used with other groups and talk about how well each worked. By the end, I hope you'll have a starting point from which to make your next document collaboration task fast and efficient.

Collaboration Design Variables -- There are several variables to consider whenever you're trying to set up a document collaboration process, especially one which doesn't rely on fancy tools that can be expensive, hard to deploy, and tricky to use. My assumption here is that you have a document you wish to have reviewed and edited by others; although documents may have multiple "owners" throughout a publication process, at any one time there should be only one person ultimately responsible for it.

Keep in mind that no one collaboration strategy will fit every situation, and you may need to come up with several strategies for different groups.

TidBITS Collaboration -- We've adopted a specific strategy for document collaboration that works extremely well for us. It's not perfect, and it undoubtedly wouldn't work in all situations, but let me explain it so you can get a sense of how you might go about using parts of it in your own collaboration process.

We rely on a round-robin editing approach among a small number of editors working on a centralized server, accessible via both FTP and AppleShare over IP. All of our documents are in Nisus Writer, which provides styles for markup, although no revision tracking or comment features like Word's. Here's how a document might go through the entire process to end up in a TidBITS issue.

  1. One of us creates the draft document, applying the styles necessary for our issue creation and distribution macros. That person also does an initial edit pass. We don't worry about small changes, but we mark meaningful changes with colors so others can see what was done. Additions or modifications appear in green, and proposed deletions appear in red. If we need to make a comment or query about a paragraph, we make the comment in red on a line by itself below the paragraph to avoid confusing the meaning of the paragraph with intratextual comments. All comments are signed with the initials of the person making the comment. If the comment or query applies only to a small bit of text, we mark that text in blue. Comments and text for deletion are both red because all red text is automatically removed just before distribution.

  2. After finishing the initial edit pass, the document goes into a folder called IN on our server. Appended to its name are a version number and a set of initials. So this article is currently called Collaboration.1.ace, which indicates it has undergone one edit pass by me.

  3. Let's say Jeff Carlson wants to take the next edit pass. Anything in IN is fair game, so he checks the document out by moving it (a Finder drag via AppleShare over IP, but possible in Interarchy via FTP with the Rename/Move command) to another folder called OUT. He also adds his initials to the filename so anyone trying to figure out who owns the document can tell by the fact that it's now called Collaboration.1.ace.jlc. Checking out the document also involves downloading for Jeff and Geoff, while I, since I'm on the same network as the server, just open it directly, although I otherwise follow the same rules. While Jeff has the document out, he can make any changes he wants, using the same colored markup scheme and comment approach outlined in the first step.

  4. As Managing Editor, Jeff often has the task of sending an article back to the original author, if it wasn't written by one of the TidBITS staff members. Here's where our system falls down a bit. When copying text from Nisus Writer to any other program (such as Eudora), color information is lost (we also prefix all comments with three asterisks so they stand out even without colors). Interestingly, a similar color pasting problem afflicts Microsoft Word as well, so we can't export from Nisus Writer into Word as a workaround. And since relatively few people use Nisus Writer, sending the original file isn't generally a useful option. Thus, our preferred approach is to send the article back in the body of an email message and ask the author to make comments and offer suggested changes just as though they were replying to a normal email message. Jeff then incorporates the changes manually. That works well as long as the changes are relatively minimal, but for more significant rewrites we find that we just have to give the original file back to the author, let him or her make the necessary changes, and then restart the entire process. When Jeff''s done, he uploads the file to IN again, and changes the name to Collaboration.2.ace.jlc so we know it's gone through the second edit pass and who did it.

  5. At any time during this process, we may send the article draft out to expert friends for quick technical review. They too get the article in the body of an email message and make comments and corrections in their reply. Whoever sent it out for review then has to incorporate the corrections and address the comments in the file, checking it out and back in again as necessary. At times, the list of initials at the end of the filename gets too long, at which point we delete some from the beginning of the list.

  6. When he's ready, Jeff moves the current version of the article into OUT, copies all the text, complete with colors and comments, and pastes it into what we call a "copy file," which is the working draft of the full issue. Once the copy file holds the latest versions of all the articles, it too goes into IN and follows the same process rules, although we only add initials to the filename when it has been moved into OUT, since that's happening on Monday when we need to know exactly who has the file open at all times. On Mondays we also tend to use email and the phone fairly heavily to let others know when the document moves to avoid wasting time in between manual checks of IN and OUT.

  7. Throughout all of this, colors and comments stay intact. At the last step before actual distribution, Geoff Duncan gives the issue the final read-through (often out loud - hopefully his neighbors don't mind) and deletes all the comments and text marked for deletion.

For the most part, our system relies on simple technology - an AppleShare/FTP server and colored text in a word processor. We intentionally try to keep our markup rules simple so there's never any confusion internally about what's happened. And when we bring in reviewers via email who don't know our approach, either they don't need to know it, or we can explain it easily.

However, our system also relies on having a small number of technically savvy reviewers with excellent attention to detail. Our approach would fall apart if anyone was overly sloppy or failed to follow the rules, especially those relating to checking files in and out, since we could end up overwriting someone else's changes. But there are other approaches that work better in such situations, and in the next installment, I'll look at some that I've used with varying degrees of success.