Agile Authoring

Quick Start

  1. Get the software
  2. Read the basics of svn especially resolving conflicts
  3. Download a copy of the paper
  4. 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 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:

  1. A central copy of the files is stored on the server
  2. Each person then grabs a copy, modifies it and commits it back to the server.
  3. 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.

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:

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

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

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

  1. Go to the download section and click on the svnX icon to download the installer. Follow the prompts ... too easy.
  2. 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

  1. In the "Repositories" window, enter the repository details, (yes password is clear text!), double click on repository and it will open a dialog.
  2. 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.
  3. Close the "Repositories" window, you don't need it anymore (password will be stored with the working copy.
  4. Drag the folder you created onto the "Working Copies" window, and double click resulting entry.
  5. 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

  1. Edit files in your working folder as you normally would.
  2. 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)