I recently discussed the preparation of manuscripts. My focus was on how you can increase the efficiency and accuracy of the process of collective writing. My thoughts are derived from, and geared towards, the kinds of writing that we do in LCV. I include some thoughts on using LaTeX and BibTeX, for example, which are widely used here, but may be relatively uncommon, or unheard-of, elsewhere. Having said that, most of my ideas, such as to use tools to allow all authors to simultaneously edit whenever possible, should apply to other kinds of writing and other collaborative processes.
I wanted to visualize what the steps in writing a manuscript are, what the tools are used for doing each step and how the overall process could be improved. I also wanted to capture who does what. I made a popplet (see below). I include guesses at who normally does different things (left side with magenta popples and second from left column with red popples). Consider that a set of tools (blue popples) for these alone would probably be something like Google Docs, Skype, Preview, JabRef, TeXstudio (what used to be TexMakerX), MATLAB, Adobe Illustrator, Apple Numbers (iWork), Gmail, Time Machine. Thoughts about what you should do as orange popples and some other notes to self as green popples. I’ve also made a table (**+here is a PDF) that lists different tools that you might find useful, some of which you may not know about.
For authors, I considered two groups, those who focus on adding content and commenting on existing content, and those who in addition to writing, complete smaller tasks, which have less to do with content, such as editing the references, or recompiling the paper from its source. I think of the latter as being one person, although it can be more than one. Sometimes two out of several authors would do those kinds of things, but normally everyone wouldn’t. I call these groups ‘everyone’ and ‘one person’.
So what are all the steps? They include: writing text; discussing everything; commenting on stuff; adding references; compiling the source (assuming there is one); exporting plots; making and editing figures; keeping track of stuff (e.g., different runs of an optimization); backing up everything; and sharing among ourselves and with others.
- Use Google Docs (or some other cloud-based tool) for writing text. You could also consider Verbosus (good for TeX), Adobe Buzzword (which looks cool), and Pages (with iWork.com). This is the right idea because it allows everyone to work on it at the same time, and it eliminates all steps involving keeping stuff in sync (emailing back and forth), which in itself eliminates a lot of headache about things like naming conventions. I believe that these cloud-based tools are essential regardless of how many people are working on it. Even with only two, not having to email back and forth saves a lot of time. The point about editing simultaneously is not really refuted by saying you only really need to do that when you’re facing a deadline. Actually having a single document that everyone can edit in real time means not even having to worry about it. You can just add text.
- Agree before working on the paper (or whatever) to only leave comments in one place. You could say, for example, that you’ll only comment on the text with ‘Insert>Comment’ in Google Docs. That’d be a cool choice because everyone can see it, it’ll stay there, it can be updated or resolved, you can get email reminders when stuff changes. The point is that if someone comments outside of that, such as by emailing a list of changes or thoughts, you’d remind each other that you want to keep everything on Google. The thing about not having a standard for that is stuff ends up all over, increasing the load on a subset of authors to put stuff in sync. It also means that everyone has to check many different sources to see the comments. Imagine you come back to the text a couple years later and you recall someone saying something about some chunk. But where did they say it? You may have to look in your email, you may have to look on things you’ve scribbled in your office, you may have to look in previous downloads of the source (where it might be as a /comment). More than likely you’ll never be able to track them down. That might imply a good commenting system would be one where you can resolve stuff, but where the comments are not deleted. Something to consider.
- Use a full-blown reference management tool like Mendeley or Zotero with a shared (cloud-based) folder for the paper rather than something like JabRef. The advantages to doing so are similar to those for Google Docs, including that everyone can edit in real time. Other options include colwiz, which should be similar. Another option is EndNote, which seems like it doesn’t cover the same functionality (e.g., reading and annotating). It’s not clear how to make it all work with the Google Docs to LaTeX thing. Integration with Google Docs, might be helpful, but even that alone might not work with TeX documents? You could try exporting to BibTeX and having that export be in a shared (cloud-based) project folder, such as one in Dropbox.
- Use TeXworks (or something like it) for TeX front end, for doing compiles). It’s probably more tool than you’ll need, but at least it’s stable and likely to work. Other options include TeXstudio and TeXShop. Remember to never edit in the .tex itself. Sometimes that’s necessary, like when it won’t compile and you need to fix something. Normal thing then would be to make the change and copy and paste back into Google. Seems like bad form. Keep the PDF in the shared folder for the paper.
- Give everyone access to the MATLAB code, so everyone has same scripts and outputs.
- Consider saving all figures as EPS so people can use any vector graphics editor on them. It’s not clear whether that’s perfect, though, so you’d want to check it. It’s possible that there would be differences with editing in various editors and things that don’t get saved out. If everyone is cool with using Adobe Illustrator I’d go with that. Again agree that you’re not going to edit stuff with different tools or with tools of different versions.
- Don’t share things via email. Use Dropbox on the main folder and put everything that’s not on Google Docs (or some other cloud) into the Dropbox. If you want to send something to someone outside use YouSendIt. You could also give them a link to the Google doc or put them on sharing there. It might be necessary for everyone involved to have a Dropbox account (and something like 50 gig), which is unlikely. If that applies, would need to figure out some other way to do this.
- Have a plan for backup. One can assume that the stuff on Google Docs is backed up their side, but you will also have copies of stuff from the downloads. Can probably make a Time Machine backup on the main project folder, although not clear how that works with Dropbox folders.