Issue tracking when writing a paper

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]".)

-
In what does any generic bug tracker (usually coupled with version control system) or advanced multi-user to-do list not answer this question. I fail how that is not a “big list” question. Tracking issues in software source code is just like tracking issues in paper source code, isn't it? – F'x Dec 1 '12 at 21:07
Emacs org-mode works well for this for me, and if the paper is written in org-mode, it works even better. – mankoff Dec 1 '12 at 21:43
@F'x I don't expect any list (sure, I know that there are many issue tracking applications). I believe that for papers it should work as for software, however: 1) I never saw anyone doing that, 2) usually when you write software, you work with other techies (which is not necessary the case when writing a paper). – Piotr Migdal Dec 2 '12 at 16:34
I would really like to see some good answers to this question. I'd hope that there are answers that can work with an existing VCS: I run svn locally, and wouldn't want to have to switch to bitbucket or some other server just to get access to issue tracking tools. – Suresh Dec 3 '12 at 16:06
I never tried it, but I'd love to give Trello (trello.com) a try in one of my next projects. While bug tracker + version control seems too much overhead for a paper, this might be the right combination of features and usability. – Federico Poloni Dec 8 '12 at 15:48

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.

-
I want to test this issue tracking at BitBucket. I'm curious whether it works or not. (And I know that it works for software dev, I have great experience with JIRA.) – Piotr Migdal Dec 1 '12 at 19:58
+1 for bitbucket and the idea of using the standard revision control tools software developers rely on -- they work great! That's the kind of tool that everybody needs to learn... starting from Microsoft developers with their idiosyncratic binary formats of the Office files :). I am working on a book with a collaborator in LaTeX, it is a nice and smooth tool. – StasK Nov 4 '13 at 2:19

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.

-
The fixme package does all of this and more, if that's all you want. But I don't think comments in a draft are the best way to handle issue tracking. – Suresh Dec 6 '12 at 7:42
For LaTeX, also check the LaTeX Wikibook and for example this post on TeX.sx for more information and suggestions – Peter Jansson Nov 3 '13 at 13:21

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".

-
Hello jb., maybe you could comment on how you apply this generic methodology to writing papers? For example, how do you link your Trello items to certain parts of a paper, etc. – F'x Nov 3 '13 at 20:38