Streamlining Draft Flow

From GersteinInfo

Revision as of 16:59, 9 April 2017

Workflow

This is the overall workflow for draft and manuscript submission. For details, please refer to the sections below (use 'Contents' above to navigate).

General

This document has been prepared by Mark Gerstein. It describes some general ideas to streamline the flow of drafts, papers, and related documents through the lab.

In general, people should try to develop drafts of the paper in an orderly fashion. The idea is not to read many drafts of papers or for a person not to write very much. My suggestion is that before even starting to write, first work out all the major scientific results and findings in powerpoints that are presented individually to me or in various sub-group meetings. Also, develop rough versions of most of the figures. After this, approach writing in a structured fashion. First, do an outline of the main results, get together a list of key references then actually start to write. Writing before working through the results or determining the overall structure of the document is frankly a waste of time for both the writer and the reader.

People should pass around intermediate drafts of the documents to sub-group members and get feedback. Try to indicate in the revision history when this was done. It's important that the documents be enjoyable and interesting to read before sending it out for review, not just to me, but at least to the other members of the sub-group or lab.

We are going to develop various ways of proofreading documents, partcularly those written by non-native English speakers. This can be done by, of course, giving the document to a native English speaker to look at at the end stage. Also, there's a number of commericial proofreading servies such as Edit My English and other things that I'm willing to pay for at the final stage of the document.

Update Apr. '14

Ideas on File Presentation for Revised Drafts

Revisions

The one thing that annoys me in revising a document is when I make extensive suggestions for changes, particularly on paper in some print out format, and then on the next version none of the suggestions have been incorporated or responded to. I think it's important when I look at a version of the document I have some indication of what the suggested changes are. Either my marked up corrections (via digital send of this) or a all-changes-file or something similar. It doesn't matter if you don't want to put in the changes I suggest. I'd at least like to have them acknowledged and not have to repeat them over and over again.

• Track Changes

When looking at many versions of a document, particularly at the final stages, it's very useful to use track changes so one can focus on just the changes. This can work with latex by just giving me the track changed version of the source file and a PDF of the formatted version (without changes). One should try to do track changes relative to the last edit, not to the original version of the manuscript. This can be achieved by accepting all the changes after an edit discussion and then starting afresh.

• Revision History

One should maintain a rough revision history of the document, that is each draft should be given a kind of draft number and some indication, maybe at the head of the draft or in an e-mail, should be given as to which drafts were sent to which people. We can use this information to decide on other people to send the draft to in the lab and also to get a sense of how many times it's been turning over. If we are working on a document in response to referee's comments, best to always send draft with at least a rough response to referees. (See below for format.)

IDs & File conventions

• Word & PDF

Use MS Word (or HTML) over latex. If you need to use latex for equations, embed them in the word file as GIFs. If you send me a PDF with equations, please try to make sure they come out OK on windows. In connection with this, [1] might be a useful link. Also, please use "doc" in preference to docx as the later doesn't work with all readers.

• Lab ID

When working on a draft, people should try and develop a one or two word lab ID -- e.g. "sandy" or "pseudopiped". This is useful in terms of organizing correspondence about the document and quickly referring to it. Later on, we will use this lab ID in the framework on the papers page.

• Email small files and Outbox links to bigger things

If you want to go for email, try to keep the size of the emailed file less than 1 Mb. If you want to go to bigger files, send a link. If you send a big message to my normal email, it will fill up a number of my mailboxes and cause messages to be bounced. If we are working on a big document, you can either send just the section you changed as an attachment or send a link to whole edited file.

• Unique names in outboxes

when sending me links to files in your "outbox" . I'd appreciate if this link be unique and that you don't overwrite files with the same name. I have my own internal file system (for "inboxes") that gets confused when you overwrite names. In particular, if you send me something like this:

http://homes.gersteinlab.org/people/joelabmember/outbox/proj1/mypaper.doc

Then you update this. Please use a link like

http://homes.gersteinlab.org/people/joelabmember/outbox/proj1/mypaper2.doc

rather than

http://homes.gersteinlab.org/people/joelabmember/outbox/proj1/mypaper.doc

• Optimal Situation

The best situation is to segregate the figures from the text and put everything in an outbox. Then send me a link to both the doc and pdf files of the text (showing track changes if appropriate) and then a link to the the figures (as a PPT or PDF). .

Submission and Dealing with the Journal

• Deprecated: See xxmg@gersteinlab.org for correct address to use for paper correspondence.
• Use the pi address for the corresponding author.
• Use templates (at http://wiki.gersteinlab.org/labinfo/index.php/Templates) for the submission letter and response to the referees

Comments on Parts of the Draft

• Affiliation
  • Way to List Affiliations for Mark Gerstein on papers
  • Mark B. Gerstein 1,2,3
  • 1 Program in Computational Biology and Bioinformatics, 2 Department of Molecular Biophysics and Biochemistry, and 3 Department of Computer Science, Yale University, Bass 432, 266 Whitney Avenue, New Haven, CT 06520 (Mark.Gerstein (at) Yale.edu)

• Affiliation for postdocs
  • Postdocs whose primary appointment is the "MB&B Department" are also affiliated to the "Program in Computational Biology & Bioinformatics" (CBB)
  • Hence, they can list both the affiliations. Mark would prefer CBB be listed first, but if they want MB&B can be listed first.

• Overall Document Flow
  • Commenting -- Don't use word's commenting feature if possible. I find this confusing. Just put them into the text directly. I use the following format: "[[MG-for-JJ: a comment for you!]]"
  • Track Changes -- Use this, if possible. If this doesn't make sense highlight your changes somehow (e.g. with yellow).
  • Spacing -- Don't double space (so that printing out the draft doesn't take a fraction of a tree).
  • Number the pages

• Figures
  • Put all the figures and tables at the end of a document -- it makes it easier to read the text.
  • If the figures take up a significant amount of space, put them in a separate file. (This makes emailing around the more highly edited text part easier.) Sometimes it's easiest to send the draft as an attachment and put the figures at an outbox URL.

• References
  • If you want to use endnote, please send your paper with its own endnote library. If there is no specified format for references, you might try just using "Harvard style" citations (Jones et al., 1998) with a flat text alphabetized bibliography. I'd format the bibliography in the following way if possible as it makes it easy to sort and merge.
  • Akerley, B. J., E. J. Rubin, A. Camilli, D. J. Lampe, H. M. Robertson, and J. J. Mekalanos. (1998). Systematic identification of essential genes by in vitro mariner mutagenesis. Proc Natl Acad Sci USA, 95:8927-32.
  • Albert, R., H. Jeong and A. L. Barabasi (1999). Diameter of the World-Wide Web. Nature 401: 130-131.
  • Albert, R., H. Jeong and A. L. Barabasi (2000). Error and attack tolerance of complex networks. Nature 406: 378-382.

• Acknowledgements
  • All my papers in draft form should just start off acknowledging funding from the "NIH or NSF and from the AL Williams Professorship Funds". We will fill in a specific grant number or other agency as appropriate at the very end, usually in proof stage. If a journal asks where the open access charges come from, again, one should just say "the NIH". Do not put in grant numbers!
  • I suggest the following boilerplate: "We acknowledge support from the NIH and from the AL Williams Professorship funds."

Proof Stage Pointers

First Author Common Courtesy

This is a new Gerstein lab "Policy". Ideally before submission, but at the very least after, the first author should send the final submitted version including all figures to every person on the author list. As a first author, you have a responsibility to your co-authors. They should be given time to remove their names if they disagree with your findings/interpretation or at the very least to state their concerns before it comes out in print.