Streamlining Draft Flow

From GersteinInfo

Latest revision as of 14:17, 7 September 2021

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.
• develop rough versions of most of the figures.

Then,

• do an outline of the main results, get together a list of key references .

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.
• there's a number of commericial proofreading servies such as Edit My English or grammarly.
• I'm willing to pay for a professional editor as well.

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 be done in several ways

• Do the track changes on the word document and create a pdf file that has the track changes. Add "-diff" to the title of this file, so I know it has the changes relative to the previous version.
• If you're using latex, make sure to highlight your changes. You can highlight with yellow. If you want to show me what you delete, you can strike the sentences that are deleted. Again, name this file with a tag "-diff" and send me the pdf version.

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. The easiest way is naming the draft with the date tag and the authors' initials in case there are more than one person editing the draft.

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. Best to send a PDF & a doc of just the maintext (without figures & supplement). Figures can be kept in a separate PDF or ppt file as necessary (see below).

• 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. Try to separate this ID with a dash or dot ("-" or "."), not an underscore ("_"), as this helps with searching.

• LabDropbox

Use the lab dropbox for the exchange of the drafts. If you want to show me multiple files, create a folder with the lab ID of the project and put all of your files into that folder. Check the link of the folder on the meetings page and send me the web address of the folder.

Optimal Situation and Example Format

The best situation is to segregate the figures from the text and put everything in lab dropbox. 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 figures (as a PPT or PDF). Here's the format currently preferred for drafts of papers and some parts of grants :

• Word doc with the current version
  • saved in the sync dropbox & send a link to this on lab archive (http://archive.gersteinlab.org/meetings/s/...). (Don't use the actual archive server anymore!)
    • Please use a "meetings" url not a link to a "homes" outbox or google drive
  • Please do NOT put figures into this . Keep the text "clean".
  • Use an ID convention & version date the filename

• email a PDF diff doc with track changes from the last edited version to the last one and also put into sync
  • You can use compare documents to generate this.
  • This should only be maintext changes v. the previous version.

• Put a PPT (preferred) or PDF of the figures saved in the sync dropbox
  • (send link to this via archive as in #1)
  • Also put the supplement and other associated files in the sync too.

• For the response to referees documents use the same approach as the maintext -- ie doc in the dropbox with email link + track change PDF attached
  • Do this even if you using a gdoc for the response

• Unique names in drobbox

when sending me links to files in "meetings". 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://meetings.gersteinlab.org/2017/12.17/privaseq3-GG-121717-diff.pdf

Then you update this. Please use a link like http://meetings.gersteinlab.org/2017/12.17/privaseq3-GG-121717-diff-v2.pdf rather than http://meetings.gersteinlab.org/2017/12.17/privaseq3-GG-121717-diff.pdf

Comments on Parts of the Draft

• Affiliation
  • Way to List Affiliation for Mark Gerstein on papers

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

Submission and Dealing with the Journal

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

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.