Zu den Inhalten springen

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:

  1. Agree on a common text editor and file format
  2. 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)
    • Then add a dash (minus sign) and a two-digit version number, including leading zeros
    • Example:
  3. 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“.
  4. The author currently writing/revising accepts/rejects all prior changes (well, maybe you leave some problematic stuff for further discussion).
  5. The author currently writing/revising adds new improvements in markup mode. If the change indicators nag you, switch the view to “final without markup”.
  6. The author currently writing/revising sends to all coauthors, possibly indicating who's next.
  7. The next coauthor (or iteration cycle) goes to step 3 above.
  8. 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:
    and repeat from step 3. 
  9. 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