25

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
  • 1
    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
10

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
3

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.

  • 3
    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
2

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

  • 2
    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
0

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

-1

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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