29

I often edit a manuscript draft with co-authors by sending drafts of a document back and forth via email. Depending on who I am working with, cloud-based solutions to working collaboratively are not always an option.

After some back and forth a lot of interim drafts begin floating around, so a lot of my co-authors either initial, date, or number a working document when we send it back and forth for edits. Some do none of this at all. I am wondering if there is a correct way to "name" a document when collaborating via email. Is there a consensus on best practices for file-naming conventions when collaboratively editing via email?

  • 5
    "correct" not sure, common sense yes - dates or version 1, version 2 or dates, times and initials are all common... – Solar Mike May 14 at 8:25
  • 8
    The key of good VCS such as git is to have a link to which the previous version is. So, ask them to mark their version with their new version number and name, at the least, but, ideally, add from which version they have constructed it (or multiple of these if this was a merge). – Captain Emacs May 14 at 9:28
  • 4
    @CaptainEmacs No need to do such manual drudgery; that's what git format-patch is for ;) – Warbo May 14 at 17:20
  • 33
    @Warbo If they can use git format-patch, they know how to use git. If they know how to use git, they will use LaTeX. If they use LaTeX, they are capable of using online repositories. If they are capable of using online repositories, they would use them for a joint document. If they would use them, the question would not have been asked. Hence, they must use either Google Docs or Word. Google docs does not have version problems. It follows that they use Word, email with incoherent threads, and inconsistent file naming for version control and they think "git format-patch" is a Romulan swearword. – Captain Emacs May 14 at 19:40
  • 20
    @CaptainEmacs I have various collaborators that use Latex and still exchange files via e-mail. Git is more advanced tech than Latex. – Federico Poloni May 14 at 21:06

11 Answers 11

28

I come from a field where none of these answers are going to work. Remember, most scientists aren't computer scientists. As a grad student, sending professors arcane rules for naming conventions would probably just be ignored. Everyone has their own usual pattern, and even if they wanted to be helpful, might just forget when it comes time to save. What irks me is people that put spaces in filenames.

As much as I plan to improve this process if I ever run my own lab, here's what you have to do:

The first author (or author leading the publication, or the corresponding author, or someone picked to facilitate) runs the show.

  1. When you send out a draft, state a date for when you'd like to receive comments by (two weeks is a good rule-of-thumb). Don't make your own edits in the meantime if you can help it.
  2. When you send out a draft, put a date on it. When people start sending you comments, sometimes people will be kind and edit one that someone has already edited. IME, that doesn't always happen.
  3. At the end of the time period, or once you've received everyone's comments, use Word's document merge tool.
  4. Save with the new date, and start incorporating edits and responding to comments.
  5. Rinse and repeat.

You will end up with a lot of files, with different dates. I keep the files from step #4 only, once you are confident in the merge. Frankly, space is cheap, and personally I find it easier to open paper-200303.docx to find an old comment than revision tools (for Word). When the paper is accepted, you can delete the old versions.

| improve this answer | |
  • This might be the best answer so far to the specificquestion... Though merge in Word? ... You are lucky if you have the expected number of pages at the end... Printing out the document and comparing them side by side sounds like a better option... (Or just use something sensible like LaTeX + git, but alas, not always an option :(0 – DetlevCM May 15 at 14:28
  • 1
    @DetlevCM I've never had major issues with Word merge, just sometimes lose who wrote the comment. – Azor Ahai -- he him May 15 at 15:32
  • 2
    This only works in fields where first authors exist. – JeffE May 15 at 22:12
  • @JeffE True, qualified – Azor Ahai -- he him May 16 at 0:06
  • Although perhaps those fields (math) can deal with Latex ... trust me I'd prefer to have a better system, this is what works in my field – Azor Ahai -- he him May 16 at 0:06
35

Not using version control is bad.

Depending on who I am working with, cloud-based[, version controlled] solutions to working collaboratively are not always an option.

You can use cloud-based solutions even when some collaborators are against them. All you need to do is: Download and email the cloud version to collaborators that refuse to use the cloud, and upload whatever they send back.

| improve this answer | |
  • 30
    The OP knows that not using version control is bad. This does not answer their question. – Dmitry Savostyanov May 14 at 10:10
  • 10
    @lighthousekeeper If an OP is following an ill-advised path, should we help them along (by answering their questions) or guide them onto a better path? I believe the latter is more useful and should be considered a valid answer, which is what I believe my answer does – user2768 May 14 at 11:54
  • Comments are not for extended discussion; this conversation has been moved to chat. Leaving these two to summarize the discussion. – cag51 May 16 at 4:44
  • 2
    I feel this is misleading as VCS != cloud. If there are objections because the cloud is bad, e.g. because it is under foreign control and well cloudy (if it's there it's there and if it's gone it's gone...), you can suggest to setup a private VCS/git repo! – Frank Hopkins May 16 at 15:29
  • That sounds like a lot of work for the person co-ordinating the cloud repository! And remember, being "against" a cloud solution is not necessarily being obstructive for the sake of it -- sometimes there are good reasons (security of confidential data; collaborators at different institutions; compatibility issues of a specific cloud solution for those of us who do not have the latest, shiniest hardware and operating systems; ethical objections to giving custom to a provider that dodges taxes) – anon May 17 at 2:35
12

The key to modern version control such as git is knowing the parent documents of a document. You thus need to be able to reconstruct which the immediately previous version is.

So, ask them to mark their version with their new version number and name, at the least, but, ideally, add from which version they have constructed it (or multiple of these if this was a merge)

Thus, at the very least, OP could use -.-.txt.

So you could deduce that that rollingstones-4.2-PK.txt has been derived by PK from (probably) 4.1. As well as rollingstones-4.2-IR.txt has also probably 4.1 as parent, but modified independently by somebody else. When you merge versions with the same number, you can omit the author and just give it the following number, e.g. if rolling stones-4.3.txt is a merge of the previous ones.

If you can afford to and people are disciplined, it would help to mark the immediate predecessor, though: rollingstones-4.4-UM-from-4.3-PK.txt. This is a bit clunky and a poor imitation of modern VCS such as git, but it allows you to deduce the parent(s) of the present version which is all you ultimately need.

To facilitate that, ask people, directly on downloading the latest version, to duplicate it and modify its name immediately to reflect the parenthood of the downloaded version.

| improve this answer | |
  • 6
    This is a great suggestion, and it works well when it works. My only worry is what happens if some contributors fail to change the file name after the edit (e.g. because "oh, it's so minor, just a line here and there"). We still fall back to history of emails to recover the tree of edits. Filename conventions can be done wrong, but email client keeps order regardless. That's why I think emails should be the primary mechanism. – Dmitry Savostyanov May 14 at 10:15
  • @DmitrySavostyanov Well, email is just a timeline. Basically it means, you have to dig out the possible dependencies anyway by hand. Essentially dynamic time warping, split according to authors, by hand. Yuck! – Captain Emacs May 14 at 10:22
  • Well, email keeps a tree of replies, so if people download the file from an email, edit it and email by responding to the same email, we have the tree of edits, not "just the timeline". – Dmitry Savostyanov May 14 at 10:25
  • @DmitrySavostyanov How do you merge? And what do you do if a new thread is opened? I am kind of beginning to get your point, but if you suggest email as VCS, perhaps you should edit your answer to explain the "algorithm" as to how to manage email as VCS. I am not fully able to understand how one would find the parents in your algorithm. I got that far to see that threads with individual correspondents would correspond to "branches". – Captain Emacs May 14 at 10:29
  • 4
    @DmitrySavostyanov In emails, there is not only no automatic merge, but no merge at all, which means, you may not know who the full sets of parents are - in emails you have usually only one parent, and sometimes even orphaned branches. That's why I do not think that emails are a good (ahem adequate) model and I suggested a more explicit approach. Of course, where the explicit approach breaks, you can then further enhance it by taking the clues from the email, but it's not something I'd like to do on a regular basis as a user. Anyway, thank you for clarifying. – Captain Emacs May 14 at 10:46
11

I'm surprised nobody has mentioned the classical "token"/"cookie" system.

The way I used to write papers with coauthors 20 years ago was using an informal token system. If I wanted to edit Section 1 of the paper, even just to fix a single typo, I had to follow these steps:

  • Email all coauthors with the text "I am claiming the token for section 1."
  • Edit section 1
  • Email all coauthors with their edited version of Section 1 and the text "I am releasing the token for Section 1."

Nobody was allowed to keep the token for any section more than some agreed limit. typically 24 hours, but that often shrank to 2 hours or even 15 minutes as deadlines got closer. In principle, everyone could keep their own local copy of the paper up to date, but in practice, it was helpful for one co-author to periodically recalibrate by claiming the token for the entire paper.

As long as everyone followed token discipline, there was no need to worry about file names. There were no version disputes, because the most recent version of Section 5.4 was always by definition in the most recent email releasing the token for Section 5.4. In particular, if you branched, it was your responsibility to merge correctly, not your coauthors'.

On the other hand, co-authors (including both PhD students and tenured Luddites) who didn't follow token discipline found themselves involved in fewer papers afterward.

While my paper collaboration has mostly moved to Overleaf+git, I do actually still use this system on the unavoidable but thankfully increasingly rare occasions that I need to collaborate on a Word document with someone who doesn't have access to Word Online or Google Docs.

tl;dr: Don't do this unless you have to.

| improve this answer | |
  • 1
    Sounds like working with a broken version of CVS. :-S – Captain Emacs May 15 at 14:11
  • 1
    It sounds messy from the outside, but I can see how this can work well. Though what happens if you work on Section 2 and another co-author starts working on Section 3 on parallel. Who merges the two sections at the end? – DetlevCM May 15 at 14:30
  • 1
    I believe it was answered - if you want, you can update your local document but usually someone says "I claim token for the paper" and updates it for everyone. I also believe that sections might often be on separate .tex files that are all included in the main file, so no merging is actually required. – Džuris May 15 at 16:16
  • 1
    @AzorAhai It doesn't matter what system you use, unless you tell the people which one you are using it won't work. Same here. It's clunky, but it has the great advantage that it does not rely on a specific technology. – Marianne013 May 15 at 19:29
  • 1
    @JeffE I feel exactly the opposite :D Navigating file longer than a screen and a half is terrible, I do file per section all the time. – Džuris May 16 at 0:37
4

If you want to avoid cloud solutions and use email, maybe choose a VCS which works offline (i.e. is distributed, like git) and has support for email (preferably built-in, like git).

There are many ways to set up such a workflow, here's an example for git. Essentially: you work in git like normal, and when you want to send someone your changes you can use git send-email; after receiving an email containing changes you would like to apply (e.g. maybe after some back-and-forth discussion in reply to a git send-email message) you can pipe that email into a command like git am to incorporate the changes.

git is well-suited to use over email, since this was its original use-case and is hence the preferred and best-supported way to use it.

| improve this answer | |
  • 1
    you are assuming they will send you a git formatted email – Ángel May 14 at 17:30
  • 3
    Most likely, they use Word. See my comment above :-) – Captain Emacs May 14 at 19:42
  • Implicitly, the question implies the use of some binary file such as Word as pointed out by others. Version control can be used with binary files, but is typically not that useful. If they use Word, I guess one could extract the xml but lets not go down that avenue... – DetlevCM May 15 at 14:32
4

This doesn't strictly answer the question, because it is about adopting no convention at all. As others have said, it is usually difficult to get authors to stick to the same system.

Assuming you use a format (e.g. MS Word) which has some sort of "track changes" feature, or a text format (e.g. LaTeX) which you can diff:

  • Let authors rename files in any way they please
  • One person (perhaps unofficially) takes responsibility for maintaining some sort of continuity of the document (i.e. keeping the structure and flow OK)
  • If the document versions diverge, this person uses the "track changes" feature to pull them back together
  • And then emails the result to everyone saying "I've incorporated everyone's changes"
  • Some authors won't work off this version straight away, especially if they were in the middle of writing something or working closely with someone else
    • But eventually they will because they don't want to be left out of the loop
    • In the meantime the "maintainer" just keeps adding their new changes to their "master" document
    • The key is that they don't need to do any work to switch to the master version.

Authors that aren't off doing their own thing will know which version to choose (the one that says "everyone's changes are in here!")

This has many other benefits like saving most authors time and hunting through emails, removing the danger of changes being lost, stressing authors about continuity problems, and having someone who is looking at the big picture of the document and can discuss that with other authors.

| improve this answer | |
2

A "modified date plus initials" combo might help, perhaps combined by a journal abbreviation if a template is followed, e.g. "Nature 12-12 BH". Personally, I find dates easier to track than version numbers. In any case, forking the versions must be avoided at all costs.

If Github/ Dropbox/ OneDrive etc are not an option, an online LaTex editor such as Overleaf might be, where each collaborator can work on one single version of the paper. Another solution is e-mailed download links, since one does not need to have an account to access a file (this has the advantage of process ownership and monitoring but includes more hassle). If lack of internet is a problem, I cannot think of something.

| improve this answer | |
0

tl;dr: In my personal opinion, the best option is to keep the filename at all times.

Here's my reasoning. The filename tells us what purpose the document serves, which information it contains. The meta information (who is the author, when the last edit was made) is saved in file properties or in special fields within the file itself. The history of edits is traditionally maintained using some version control system (VCS).

In your case, you use email as your VCS. The emails are timestamped and your email client allows you to sort emails according to this date. Emails also give you information about the last author. If people send their edits by responding to the email with the version from which the edit was made, the email client keeps the whole tree of edits, just like git, allowing you to find a parent for every version. A tree of emails is a direct equivalent of a git tree. You may want to create a filter to put all emails with this file attached in a special folder to separate them from the rest of your communications. Other than that, email is already a minimalist and incomplete (no automatic merge for example), but working VCS.

Since you already have a VCS, modifying filenames to code the same information is unnecessary and inconvenient, and should be avoided.

PS: And it goes without saying, email is a much poorer VCS compared to e.g. git, so you should at least offer your collaborators to try using a better system for collaboration.

| improve this answer | |
  • 2
    Email is a horrible VSC, emphatically not recommended. At the very least, OP could use <original filename>-<version number>.<version-subnumber>-<last change author>.txt. This is a poor imitation of modern VCS such as git, in terms of allowing one to deduce the parent(s) of the present version (which is the key here, especially with multiple authors). All said, not using a proper VCS is definitely a pain. – Captain Emacs May 14 at 9:23
  • 1
    @CaptainEmacs Perhaps, you would like to post your comment as an answer? – Dmitry Savostyanov May 14 at 9:37
0

If you must share files in such a way (and often you just have to, despite the many wonderful version control, cloud file-sharing and collaborative editing tools out there), I suggest a format such as mainfilename-timestamp-initials.

E.g., cure_for_cancer-202005011030-jb.tex, where the timestamp is for 10.30am on May 1, 2020. That makes it easy to sort multiple versions of the same file lexicographically (i.e., by file name). But of course, you've then got the challenge of getting collaborators to follow the same convention.

| improve this answer | |
  • 3
    It's not human readable or writable. – Anonymous Physicist May 15 at 7:50
  • 3
    @AnonymousPhysicist Meh. I'm a human, and I read those things all the time. YMMV. Choose a timestamp format you prefer, but that particular order at least sorts well. – beldaz May 15 at 7:51
  • 3
    The ISO date/time format is basically that one, and it includes some better defaults for separators. – Federico Poloni May 15 at 17:45
  • 1
    minute time stamps are probably a little fine-grained, days work just fine (especially if there are initials too) – Azor Ahai -- he him May 15 at 18:59
0

In my experience, the single biggest problem is that the file's "last modified" metadatum often ends up reflecting the time it was "last saved/downloaded". That means that establishing where it fits into a workflow can be a nightmare.

My solutions, which do not require computing expertise (I work in a humanities discipline, so one cannot assume everyone is comfortable using the suggestions in other answers), are as follows:

  • enter dates of recent revisions and associated author monograms in the page header manually (e.g.: "JB 31/04/2019; revised JRW 02/05/2019; JB comments 03/05/2019") -- this makes the information easy to find and ensures it is included on every page of a printout (yes, I like to comment on versions by annotating a printout by hand!); and

  • all file names commence with the date of the version in yyyymmdd format (e.g.: "20190503_JB_comments_re_20190502_JRW_Methodology"), in order to facilitate quick sorting and unambiguous identification of recent versions on computer filesystems.

| improve this answer | |
-1

I would take a stab at semantic versioning, as suggested by the people who run Github.

In short: append a series of three digits to the end of the filename. For example: myfile-1.0.0.txt. When someone sends it back to you, whatever they respond with, you can tick up your next version to some identifier in that format which clearly counts as numerically greater.

| improve this answer | |
  • 1
    This doesn't work if two people edit 1.0.0 independently. – Anonymous Physicist May 15 at 7:51
  • @AnonymousPhysicist: So the primary author/OP takes it and bumps it up by one. If the co-authors refuse to help at all, then it's the OP's responsibility to correct. – Daniel R. Collins May 15 at 14:18

Not the answer you're looking for? Browse other questions tagged or ask your own question.