Quick Start

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.

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.

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:

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