Issue tracking when writing a paper

Question

When writing papers (and even more - when revising after collaborators', or reviewers', remarks) it's hard to keep track what is done, what needs to be fixed, what cannot be fixed, when opinions of authors are equivocal (and when an issue raised by one author is not supported by the others).

Moreover, it generates to a lot of e-mail traffic, often with a short remarks.

The question is, is there a issue tracking software (or workflow) suitable for reviewing academic papers?

(As a side note, I'm familiar with JIRA, but never used it for papers. I'm the most interested in answer when someone actually uses a given method, not "well, I never tried but here is [a link to a random issue tracking software]".)

Answer 1

It sounds like you want to use a version control system, combined with a bug tracker. Luckily, Mercurial combined with an online bitbucket.org repository provides a nice workflow. When remarks or notes appear, you add them to the issue tracker at your bitbucket page (note that bitbucket provides private repositories). See this example from one of my software projects.

When working on the paper you can select one of the issues, fix it, add to your repository, with a mention of the issue number in the bug tracker. This sounds like it could provide you with two important things: managing of the growth of your paper, and organizing your workflow of handeling the interaction with the other authors.

Answer 2

If you are using LaTeX to write your papers, some simple macros can be used to add comments by each author. Moreover, the macro can be put within an \ifdraft so that all comments can be omitted from the final version by setting \draftfalse. Examples below:

% define a new \if to certain things in draft mode only  
\newif\ifdraft  
\drafttrue  
%\draftfalse  

\newcommand{\mycomment}[3]%  
{\ifdraft \textcolor{#2}{{\bf\textsc{#1}:}~~#3} \else \fi}  

%% individual reviewer macros.  
\newcommand{\alice}[1]%  
{\mycomment{alice}{blue}{#1}}  

\newcommand{\bob}[1]%   
{\mycomment{bob}{green}{#1}}  

Use in the main .tex as:

Thus P=NP. \alice{I dont think this is a real proof.}

Advantage of this technique over issue trackers is that everything appears in the draft.

Answer 3

I use Trello which is really a generic list app, there I use Kanban methodology (1, 2), so for each project there are four lists:

• TODO
• Doing
• To Verify (means that task is done according to person who did it, and someone other should verify it)
• Done

How you can use this methodology:

• Split process of preparing manuscript into tasks (this is possible after you have decided outline of the article). Tasks could be: "Prepare image depicting architecture of our system", "Prepare section about data acquisition equipement we use" and so on. At this phase you should have most of needed results, but not necessarily all.
• You can assign tasks to particular persons, but this is optional.
• All tasks start in TODO sections.
• When someone starts doing a tasks they drag it to Doing section (you should minimize amount of tasks in this section).
• Done tasks are moved to Verify section where someone (may be senior member of team --- depending of the aragements) checks them and moves to Done.
• You might need add section: Waiting, where tasks is being done but is waiting for something external to happen (like editor response, or some computation to get time share)
• When in review phase you should add changes requested by the reviever/editor to TODO tasks. And then maybe add column: "For the next communication with reviewer".

But really Kanbaan's heart is: "Start with your current workflow, and then change it to increase throughtput and minimize amount of work done concurrently".

Answer 4

Unless you are doing massive compendiums, I recommend just to babysit things by the first author. Think collaborative writing programs or tracking are more of a pain than they are worth.

Have anyone sending proposed edits do so in MS Word with track changes. To you, first author, directly, not to the group. Use separate mailings, not group ones, to avoid reply all spam. Sometimes, they will need to send numbered suggestions or the like, but just process those than.

Use numbered version control for the files for each generation of the paper. Compile the suggested edits, drafts, reviews etc. in an electronic folder (subfolders if needed.) I really doubt you need to go back to the suggested edits much, especially if you process things in turn, but at least they are there. If people don't rename the Word file (often they won't) than you do so when you save (usually with some name and date associated with the review/collaborator). If they have emails with edits or the like save those into the folder also or into Word files (again renaming to be clear).

Resist the impulse to let a paper become a committee report. Have a clear leader (first author) and make decisions. It is fine that reviewers or collaborators got to make suggested edits, but you should view that as enough of a gift and then make the hard decisions. Sometimes you can even blame it on conflicting edits (truthfully or not).

Of course, you should carefully consider input and use it. But DON'T be a reed in the wind. Be a leader. Papers need that. That is a gift also. Truly.

[All of this applies to joint work product in the corporate world as well. Give people a chance to "have input" so they feel a part of the process. But be an owner/leader of the end product and not a compiler.]

Answer 5

I'm testing GitHub ( with GitHub Desktop and Atom ) Not really adept in it, but looks like a potential candidate to me.

Here's a project of mine, if you would like to see how it looks right now-

CTM