Quick Start

Get the software
Read the basics of svn especially resolving conflicts
Download a copy of the paper
Start editing...

Motivation

The aim is to create a set of guidelines and tools to allow a small group to effectively collaborate in writing a paper. The process should assist in rapidly arriving at a paper that is clear, concise, and has a consistent style throughout. The process should also cope well with authors of different experience.

Some common writing models we want to avoid or improve on are:

Convener	one person writes the paper with everyone else contributing parts through that person. There is a lot of work for the convener for relatively little reward in this model.
Serial authoring	the paper is passed from author to author, each contributing and modifying in turn. This model seems to be optimised for exposing bottle-necks.
Assigned sections	everyone is assigned a section and then it's all massaged together at the end. It is difficult to maintain a consistent style with this approach and it only works well if all authors are experienced.
Engineering paradigm	plan first down to the smallest units possible and then implement. This works well in an engineering scenario where planning is much cheaper than building. For authoring both activities are much more equivalent and fluid and it doesn't make much sense to have this division strongly emphasised.

The writing model presented below takes ideas from all the above models though it is mostly a combination of the Assigned Sections and Engineering approaches but in a self-organised way. It tries to encourage parallel authoring (instead of serial) and everyone participates in the convener role, assisted by software.

This situation is not dissimilar from software design and programing, and heavy use is made of ideas from Agile software development in particular from Extreme Programing.

The Rules (how to play nicely)

The aim of the following "rules" (more like guidelines really) is to create a dynamic environment for rapid publication. By themselves each rule doesn't achieve much, they are designed to reinforce each other the achieve the right dynamics.

The Story. An outline should be written in the comments (or in a special environment) in the file and maintained as the paper progresses. These comments set out the story and ideally should be worked out as a group involving everyone, near the beginning of the project. The story should give the entire structure of the paper, giving the key ideas and how they are linked. It doesn't have to be verbose or well written, it just has to capture the ideas.

The story is not set in stone. Authors can change the story as the writing progresses and a new spin is put on the paper. That said, the story shouldn't change too much in practice since it expresses the point of the paper. Changes to the outline should involve as many of the authors as possible and should be well thought out --- after all you're changing the direction of the project.
Revision control. A system of revision control is needed. This allows the latest version to be constantly accessible to all the authors, it's easy to see what the latest changes are using utilities like diff, and previous changes can be rolled back if something goes pear-shaped.
Server copy should always compile. Do not commit a change back into the server that doesn't compile. If you make a change that breaks the LaTeX then you're in the best position to fix it. It would be a pain for the other authors if they had to start by fixing up someone else's errors.
Everyone owns the lot. No, this isn't a communist takeover, how about "everyone gets the blame"? Everyone should be able to (and should) edit all parts of the manuscript. The manuscript should be a joint thing, not a collection of separate monologues. This is key to a consistent style and to preventing bottle necks in the process. The editing occurs in parallel --- this is the key to speed.
Frequent integration. After working on a local copy of the paper, changes should be committed back into the server as soon as possible. There is an optimum frequency to committing changes --- too slow and the chances are high that someone else will edit the same section, too fast and it will be really frustrating for anyone else to make a change. The ideal seems to be on the order of an hour or two, and you should never hold onto changes for more than a day. Treat the re-integration like you would saving a file that you're working on. Hitting this optimum will reduce the severity of conflicts when multiple people are working on the same part of the file, and it ensures the server is up to date.
Communicate!. Frequent communication is necessary for the process to work. Let others know what you are working on, especially if the changes affect many parts of the paper or alters the story.

The different rules reinforce each other, but they all hang on the story: you are finished working on a section, if it conforms to what is in the story. It is also easy to spot where the weak sections are and what is missing. The story means multiple people can work on the paper in parallel and know it will fit together as a whole. It means everyone can own the lot --- if you can find a better way of fulfilling the story than what is written then you rewrite it. It means you can commit changes frequently since at worst you can provide a partial solution that could be completed by someone else (you've all agreed previously on what that section should say in the story).

Quick Introduction to SVN

Svn or subversion is a revision control system, that allows changes to be tracked in files. It is multi-platform, net-friendly, and fairly mature. It grew out of cvs, so if you are familiar with that system, most of svn will also be familiar.

If you are not familiar with version control, think of it as a shared hard-drive where everyone involved can open and save files. There is a free SVN book available in html or pdf, which has all the gory details. Below is a very quick intoduction to get you going.

Work Cycle

Svn proceeds along a copy-modify-merge model:

A central copy of the files is stored on the server
Each person then grabs a copy, modifies it and commits it back to the server.
If someone else has updated the server copy in the meantime (this is called a conflict), you will need to merge the new server copy with your changes before you can resubmit your version.

(Reproduced from subversion book)

Typical Commands

The typical commands involved for the command-line version of svn are listed below. Graphical versions should have equivalent actions.

Updating your working copy: svn update
Making file changes svn add, svn delete, svn copy, svn move
Examine changes: svn status, svn diff, svn revert
Merging changes: svn update, svn revert, svn resolved
Commiting changes: svn commit

Resolving Conflicts

A conflict is when you try to check-in your changes and discover that someone has changed the same section of the server version.

three files are created in addition to your local copy which is modified. Say you checked-out revision 20 of file.tex from the server, modified it and tried to check-in the changed version only to find it's in conflict with a newer server version which is now at revision 23. This will leave you with:

file.tex: this file has been modified to show where the conflicts are. The conflict markers are:
```
<<<<<<< .mine
... your changes ...
====
... server version ...
>>>>>>> .r23
```
file.tex.mine: This is your file as it was just before check-in.
file.tex.r20: This is the file you checked-out from the server before you made your changes.
file.tex.r23: This is the file currently on the server.

Now you have several choices as to how to resolve the conflict:

You can edit file.tex, choosing the version you want to keep (or a new version) and deleting the conflict markers.
You can copy one of the extra files over the top of yours to enforce your version or the servers version.
You can issue the command svn revert to undo all your changes,
or you can use some fancy merge tool that some GUIs have.

Once you've decided on what to keep issue the command svn resolved and this will delete the extra files removing the state of conflict. Now you can commit your changed version to the server (unless you took too long resolving the conflict and someone has updated the part your working on in the server version yet again, in which case you will have to resolve the new conflict).

There are two ways to minimise the pain of conflicts --- keep changes small to make it easy to resolve conflicts i.e. frequent integration; and communicate with the other authors. Send an email round saying you're going to work on this or that section, or "hands-off I'm about to make sweeping changes" etc.

Software

There are nice free clients for Windows, Mac and Linux. Also the command line form will work on all platforms, and popular editors like emacs have built in support for svn.

Windows Client

The nicest client seems to be tortoisesvn which integrates directly into the Windows explorer. Most of the commands are available via a right-click on the working copy of a file.

MacOS Client

A reasonable client to use is svnX. It's not as nice as the Windows client but it works OK.

Installing

Go to the download section and click on the svnX icon to download the installer. Follow the prompts ... too easy.
You will also need to grab the command-line svn binaries, follow the link off the svnx web site (See Martin Ott's binary packages) click on the latest subversion package in the menu on the right, this will be a zip archive. Download and open and install

Getting a working copy

In the "Repositories" window, enter the repository details, (yes password is clear text!), double click on repository and it will open a dialog.
choose latest revision, click snv checkout, create a new folder somewhere for the working copy and svnX should download the latest version to that folder.
Close the "Repositories" window, you don't need it anymore (password will be stored with the working copy.
Drag the folder you created onto the "Working Copies" window, and double click resulting entry.
Click off "smart mode" (that will only show you files that have changed so window is initially empty). You should now see all the files copied from the server.

Commiting changes

Edit files in your working folder as you normally would.
Refresh the view in the "Working Copies" window. It will show you which files have been modified. Select the files you want to commit, click commit, enter the log message and your done.

Other svn commands Well play around, it's a Mac after all.

Linux Client

Use the command-line, damn it. What kind of linux user are ya?

Command Line

The command line version is simple, powerful, and supports all features. If you're a command-line-phobic there are a range of different graphical versions for different platforms (see above)

Check out a working copy with:
```
svn co svn://svn.physics.uq.edu.au/alexei/project  project
```
This should create a directory called "project" with the latest copy of everything, you'll probably be prompted for username and password.
Edit the files with whatever editor you want.
Add files with:
```
svn add ..files...
```
Check in a new version back to the server with:
```
svn ci -m 'Comment ...'
```
depending on your setup it may launch an editor for you to type in your comment anyway

Other useful commands are:

svn diff  (show differences between local and remote files)
svn status (summary of what's changed (nothing=no change))
svn ls (list contents of servers repository)
svn help