Tips for manuscript collaboration
I've been bitten too often by needless additional work & hassle when cooperating with colleagues on manuscripts. A problem that frequently recurs –and can be easily solved– is version control. There are well-developed tools for this in software development (e.g. git), which would be met by more than the raised eyebrow by most scientists. The lowest common denominator: at least intelligent file naming.
File naming should be:
- as short as possible (but not shorter)
- consistent
- sort alphabetically in ascending order
- disambiguate submitted revisions
My take on this:
- Agree on a common text editor and file format
- Start with a good title
- Short yet expressive, so generic that it makes sense for all involved. For example, begin with
FIRSTAUTHOR_ARVO2013 (for a conference, no need to add “abstract“, what else for ARVO? Further, “manuscript” or “paper” is typically not necessary)
or
FIRSTAUTHOR_PERGvsPhNRinGlaucoma2013 - Then add a dash (minus sign) and a two-digit version number, including leading zeros
- Example:
FIRSTAUTHOR_PERGVsPhNRinGlaucoma2013-13.docx
- Short yet expressive, so generic that it makes sense for all involved. For example, begin with
- The author currently writing/revising the manuscript first saves under a new name: ONLY incrementing the version number (the 2-digit number after the dash before the extension of the file name). Do not add date, or author initials, or (worst offence ;-) “final“.
- The author currently writing/revising accepts/rejects all prior changes (well, maybe you leave some problematic stuff for further discussion).
- The author currently writing/revising adds new improvements in markup mode. If the change indicators nag you, switch the view to “final without markup”.
- The author currently writing/revising sends to all coauthors, possibly indicating who's next.
- The next coauthor (or iteration cycle) goes to step 3 above.
- Revisions (after coming back from journal review): add “R1” (or R2, one digit should be enough here :) at the end of the name, before the dash like so:
FIRSTAUTHOR_PERGvsPhNRinGlaucoma2013R1-01.docx
and repeat from step 3. - Saving while writing
I'm in the habit to save at least once per hour (or per paragraph); and I like to keep the previous versions for a while. To stay within the guidelines above, I add a single letter at the end. When I'm ready to send to my coauthors, I send the latest version without the trailing letter.
Michael Bach