Collaborative writing in the 21st century

Every now and then we have to play with others. It doesn’t seem to matter how often our parents told us to share, we can still find it difficult. I’m spending a lot of time with my two year old son at the moment, so this feels a pertinent perspective!

When it comes to collaborative writing, we can make things easier for ourselves. Thankfully there are great tools available to help us work together with the least stress and effort. If you jointly write documents by emailing word processing files (.doc(x), .odt, etc.) with tracked changes between numerous authors, then this is the post for you.

phd101212s

The disaster of not using version control. From http://phdcomics.com/comics/archive.php?comicid=1531

Tracked changes seemed amazing when they first came along, but they quickly become tedious with lots of iterations and co-authors. Tedious includes, making the document slow to work with, difficult to read and you can only work on the document in sequence, not at the same time.  A better alternative lies in using version control to manage your document history. For this, there are basically two paths: full version control software (e.g. Git, SVN) or online writing tools like Google Docs. The latter method is easily accessible, but you are surrendering full control and the finer points of version control; plus the software you can write in is limited. I’m going to focus on full version control using Git in this post. I’ve written previously about Git, but if you’re new to version control then you should work through the lesson from Software Carpentry.

What software you write your documents in is less critical than how you collaborate. You need a system where all changes are logged, but your default is only to see the latest version of the document. To get the best results from version control, you need to write in plain text (e.g. LaTeX, markdown, etc.), so get writing in a text editor! Word processors (Word, Writer, etc.) don’t store text in a plain format, so it’s hard for version control to track what has changed. One of the biggest advantages I find of moving away from word processing software is you stop faffing about with formatting and concentrate on writing.

What does version control look like? Well, on your computer your document looks like the latest version, in the repository you can see the path the document has taken. Here’s an example of a document written in markdown and managed in Git: https://github.com/OpenHydrology/publications/blob/master/OHstat_BHS.md. If you click the history button you can see a full change log for the document. Clicking on each change log code will show you exactly what changed on each line. Here’s an example, which shows the word ‘literally’ removed from one line. For interest, this document was submitted to the publisher in Word, but the key was the document was collaborated on by three people in different places, often working at the same time and you can’t do that emailing a (e.g.) Word document. If you were paying close attention to the example above, you’ll have noticed each sentence was on a new line. Software like LaTeX and markdown wrap these to the same paragraph, unless there is an empty line in between lines of text. It’s good practice to put each sentence on its own line as it makes tracking differences much easier, I also find it makes my brain think much more about the content and purpose of each sentence.

The easiest way to use Git is with an online repository like Github or Bitbucket. If you don’t want to use the terminal to interact with your repository you can also use graphical software to manage your repository, Git Kraken looks excellent. Get started now to achieve more with less effort (after the initial learning curve)!

Advertisements