Come Together: Document Collaboration, Part 2
Last week I looked at some of the variables involved with creating document collaboration systems, and walked through the process that we use with TidBITS. This week I’m going to look at several systems I’ve used personally. Discussions in TidBITS Talk have also introduced some tools with which I have no experience, so make sure to check out that hot topic for a more complete picture.
Hit the Books — I’ve written books for a number of different publishers, and with one exception, they’ve used similar collaboration processes. In most cases, I’m a lone author working with one or two editors, which means sending chapters back and forth via email is all that’s necessary. Sometimes publishers like to have draft chapters submitted via FTP, but that’s proven more trouble than it’s worth.
In each case, the publishers dictated using Microsoft Word as the document format. Although I wrote my first two books in Nisus Writer and exported to Word when I had to send them in, I’ve stuck with Word since. I far prefer writing in Nisus Writer, but the pain of exporting, importing, and massaging the text – often multiple times per chapter – overwhelmed my preferences.
Before Word 6, major changes to the text were marked with simple colors (never character styles, which could slip through to layout), but since then each project has relied on Word’s revision tracking with mixed results. It’s nice, particularly with multiple editors, to identify who made which changes when, but documents with revision tracking become messy quickly. You can hide some visual clutter by setting the style of deleted text to be Hidden rather than Strikethrough. Even still it’s easy to cause confusion around paragraph breaks when adding and deleting text while using revision tracking, particularly when paragraph styles change at those points in the document. Plus, although Microsoft tries to make it easy to accept or reject changes, it’s so much work to address a large number of changes in a book-length document that you tend to accept them all and move on.
Conventions for comments have also been similar between projects, with comments appearing on lines by themselves after the paragraph in question, usually in a special Comment paragraph style to differentiate them from the text. With multiple editors or reviewers, convention called for everyone to sign comments with initials. That approach has worked so well that even after the appearance of Word’s comment features, I’ve never been asked to use them while writing a book. I suspect they’re too unwieldy for serious use: – the yellow comment pop-ups are annoying, the comment pane is awkward and uses too-small text by default (and in Word 2001 on the Mac, the comment pane’s Close button improperly requires two clicks to activate). Also, since Word insists comments be attached to at least one word, people tend to select lots of text for the comment, thus making large sections of a heavily commented document a bright yellow.
My Eudora Visual QuickStart Guide was an exception to the process above. It has relatively little text, many screenshots and captions, and a specific layout, all of which combined to make me do the writing and layout directly in QuarkXPress. Since QuarkXPress 3.3 lacks a good built-in way to make comments in files, I sent the files to my editor, who printed them out, marked them up with a red pencil, and sent them back via UPS. It sounds crude, but because so many comments related to layout (kerning, alignment, and so on), on-screen proofing probably would have been less accurate and more work.
Magazine & Web Writing — Magazine and Web writing is similar to books in terms of the number of editors (one or two at most) and the methods of exchanging files (always email). Magazines also rely primarily on Word for their document format, although Web publications often prefer either straight text in the body of an email message or HTML.
With most periodicals, comments are relatively minimal because the articles and the deadlines are short. A longer piece for a monthly magazine is more likely to undergo significant editing and require multiple passes by different editors. One such publication had some conventions that had apparently evolved organically, since they had the right idea, but didn’t go far enough. Changes either weren’t marked at all, were marked in blue, or were handled via Word’s revision tracking. Either of the last two would have worked fine, but the editors often weren’t consistent, which writers found confusing.
Similarly, although some editors put their comments at the end of paragraphs, others inserted them right in the middle of the text. A few long comments inside a paragraph made it easy to lose track of the actual text. As with the book editors, no magazine editors I’ve worked with have ever used Word’s comment feature. Some other situations I’ve experienced have been quite different, however.
Legal Documents — When I helped start the XNS Public Trust Organization, the other directors and I worked on a number of long, complex documents – things like our charter, the XNS Global Terms, and various legal agreements. Although there were only four board members and our lawyer, we didn’t have an author/editor situation, a centralized server, or reviewers who were publishing professionals.
The approach we used was to email Word documents around. Because of busy schedules, we were able to use a round-robin approach, so each of us was able to see the previous comments with the exception of our lawyer, who worked in parallel with the rest of us. (I tried to use Word’s Compare Documents and Merge Documents features to merge his comments and changes with a complete lack of success.) We used revision tracking somewhat, but since we were mostly reviewing and discussing these documents, relatively few changes were necessary. However, we ended up using Word’s comment feature heavily (about 100 comments over 2 documents), and although it worked acceptably, I found it clumsy for heavy use.
An unusual situation occurred when we had to finalize the XNS Global Terms just before launch. Delays meant we were working under a tight, one-day deadline, and we had about ten people involved, half of whom were lawyers. Initially we tried assigning the documents to a single person and hashing through remaining issues in a conference call, but that proved impractical. One of the lawyers recommended taking it back to email but keeping one person in charge of each document. Since the original documents were in Word, we kept them there, even though our eventual goal was to hand them off for conversion to HTML that evening. Plus, even though we were using a variety of Macs and PCs, everyone had a recent version of Word.
Word’s revision tracking worked extremely well in this case, since it marked clearly what had been changed. We had no copy editors waiting at the end, so it was important to make sure that even small changes were marked. We used Word’s comment features occasionally when remarking on something in the text that only the document owner needed to see, but we kept most of the commentary in the email messages used to carry the attached documents around. That let the discussion run fast and free (I set Eudora to check mail every minute) without forcing everyone to open and scan through each document. Putting comments between paragraphs, as I’ve done in most other projects, didn’t happen, in part because people were afraid to add text to the document that might prove confusing to strip out later, and in part because we didn’t have time to agree on comment conventions.
One lesson I’ve learned from these experiences is that the utility of Word documents is significantly hampered by having lots of user-defined styles in the document. Without a fair amount of care, not to mention knowledge of how Word styles work, a Word document rife with styles is a copy editing minefield just waiting for reviewers to walk through. The documents from these collaborations were fine in terms of content, but an utter mess otherwise. Some paragraphs were in the wrong styles, others appeared correct but had in fact been "fixed" manually, and almost anything Word did automatically (like numbered lists – a major portion of legal documents) was almost certain to be screwed up. Cleaning up the documents was easier than reformatting from scratch, but not much.
Simple Document Collaboration System — To distill my experiences with the processes above and from the TidBITS system I described last week, here are six pieces of advice for creating a successful document collaboration system that revolves around files intended for some form of publication, be it a group term paper, team report, magazine article, or technical book.
Settle on a format before starting. In all likelihood, it will be Microsoft Word, but if you choose something else, make sure everyone has software that can open and edit the files. Pay special attention to cross-platform issues. Relying on other programs to import and export is often a significant obstacle.
Test your distribution mechanism before relying on it at deadline. Email attachments generally work well these days, but a test can save major headaches. See our series of articles explaining email attachments for assistance.
Agree on basic conventions for marking changes. Use either colors or Word’s revision tracking to mark changes, or if your editing environment has no color capabilities, some sort of intratextual markup (but be sure to remove it at the end). Mark changes when they’re at all major. With Word’s revision tracking, it’s often best to have Word hide deletions to make the document easier to read.
Agree on how comments will be made, either by putting them between paragraphs (in a different user-defined style or with some prefixed characters) or by using Word’s comment feature. If you’re using Word, make sure everyone enters their initials in the User Information tab of the Preferences so comments are identified, and if not, make sure everyone signs their comments.
Encourage consistency and adherence to agreed-upon rules. This is primarily important when multiple people are making roughly equal contributions to documents with lots of formatting. In situations where you just want comments or are working with minimally formatted documents, it’s easier to let reviewers work however they want and integrate comments manually.
Make sure you know who will be responsible for assembling the final document, which will involve integration of comments, approving changes, removing all markup and comments, and general copy editing and document cleanup.
Going Online — All of these systems discussed above used the Internet purely as a transport mechanism. In the next installment, I’ll look at several services that offer collaboration environments via the Web with no need for special software or plug-ins of any sort.