05/25/13 15:30:06

Our Collaborative Scrivener Workflows

I read this post by Jefferson Smith on his cloud-based Scrivener workflows. It is a recommended reading for all Scrivener fans. Though I can’t quite agree on the backup and collaboration section.

It is true that Scrivener really isn’t that good when working with a document where two editors work on one document, but if that really happens you’re not out of luck. It just gets a little more complicated.

What I’ve learned from collaboration is that I always want to create a VCS (versioning controlled system), such as Git, repository. The reason for this is really simple. I trust no one not to screw up something. Be it unintentionally or with good intention. A versioning control system keeps me sane in the times when a project becomes complicated and everybody is head over heels trying to fix something.

That said, I also would encourage everyone to use Scriveners built in backup and versioning. You can save a revision of a current document when it’s highlighted in the document list, then type ⇧⌘5. This causes a new Snapshot to be created. To view these snapshots, or to make one manually, go to the Documents menu. If this is all you need and feel like Snapshots will resolve most problems you run into, then you don’t need to read the rest of this article. For a slightly more advanced, but also more fail-safe approach, continue reading.

Now for a basic understanding of Scriveners internal workings. A document, as I’m using it here, is not the Scrivener project — the .scriv file you see in the Finder. A Scrivener project consists of many smaller documents contained in it. You find all documents in this .scriv folder under Files/Docs. They are saved in rich-text format (RTF). A file format that opens directly in TextEdit. In fact you can just do that.

I would not recommend sharing a .scirv project through cloud storage such as Dropbox for the same reasons Jefferson explains. If two editors happen to edit a document at the same time and their saving interval is slightly off by a couple of moments, Dropbox will not create a “conflicted copy”. Instead it will assume the file has been saved once on one computer and then on another — overwriting changes. It is true that Dropbox will keep both revisions, but to the user it will appear as though everything is fine. Chances are that it will not occur to anybody that there is text missing until the very last moment. Bad.

But if you keep everything organized using a versioning system, it will pick up the changes from both editors, because they were editing the same document on their end. In that case you can, in fact you have to, resolve the conflict manually. RTF is, although its entitled “rich text” really just plain text formatted weirdly. You can look at the file (in fact the differences) in a viewer such as FileMerge or Kaleidoscope. Although formatting will probably be lost during the comparing and restoring steps, you have a good chance to recover the text! Some Diff viewers are not so beautiful, but they are free and get the job done.

In one case I had both editors working on a Scrivener document, where both created new documents within the project. Both checked in and committed their changes, but only one project contained the last project state and documents of one editor. In this case a diff viewer, on the file level, will tell you what files are missing from a project. A conflict of the .scrivx project, which basically contains the structure of the Scrivener project and all related files, will indicate such a conflict. You can manually open these files with TextEdit or any other editor and manually add the missing documents to the project.

So versioning is really great. Sharing a project is bad. Having two editors working on one project is possible, but working in the changes is not that straight forward and easy.

What I found works best is to be clear on when and what someone does in a project. Communication is key. In our case we had both of us contributing to a particular project. It was clear from the beginning that we will split up the work between chapters. So the one person was mainly editing documents the other person was not working on. I found that works best for us. We use Scrivener’s Labels feature to distinguish which person edits what. We are also very strict on backup and revisioning rules. Backup early, backup often, commit and push often. The more strict everyone is about these strategies, the better it is for the project. Mistakes can happen though, we’re all just human. In those cases some manual recovery brings everything up to speed quickly through Git.
Git has some really nice interfaces for OS X. You don’t need to open the Terminal mostly.1Tower and SourceTree are two of the most recommended ones.

I would also encourage you to use all the other features Scrivener offers. Commenting, highlighting and so forth. I am always astonished by how much Scrivener has implemented to work with long texts. Such. A. Great. App.

  1. (You can, if you’re nerdy and enjoy that kind of stuff though.)