Streamlining Draft Flow

From GersteinInfo

(Difference between revisions)
Jump to: navigation, search
(Workflow)
(Comments on Parts of the Draft)
 
(13 intermediate revisions not shown)
Line 2: Line 2:
This is the overall workflow for draft and manuscript submission. For details, please refer to the sections below (use 'Contents' above to navigate).
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.
-
* '''Drafts + revisions'''
+
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
-
[1) track changes; 2) do 'diff' versions; 3) sync in Dropbox + email; 4) separate figures; 5) remember to add funding acknowledgements with precise grant number]
+
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 .
-
* '''Submission'''
 
-
[1) Use pi@gersteinlab.org as Mark's corresponding author email; 2) get access (Mihali) to pi3 email account to get all emails from journal; 3) get access (Mihali) to journal usernames and passwords]
+
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.
-
* '''Proofs'''
+
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.
-
[1) CHANGE corresponding email to mark@gersteinlab.org; 2) make sure grant number is in acknowledgements; 3) if NIH-funded, make sure journal publishes in PubMed Central (send email to editor to confirm this)]
+
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,  
-
* '''Post-proof admin'''
+
* 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.
-
(a) Do a homepage image, pad with white space to fill out exact specifications, viz [https://urldefense.proofpoint.com/v2/url?u=http-3A__info.gersteinlab.org_Homepage-5Fimage-5Fgallery&d=CwIBaQ&c=-dg2m7zWuuDZ0MUcV7Sdqw&r=e3g5MXVeiXZuf60bhhzWoOI0FMwKqm-QmSMQiL1sQ-U&m=IaQfwVJNTOGZFc6xlJCQoT9slGbbS4jfjsREMorjhaA&s=S6MBVTLoQ9JVzF_C75cORV5EL7kGXEgZCYyZDFdTg54&e here]
+
== 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. 
-
(b) Do a papers page rebuild, requires the PubMed ID for this, and another internal ID obtained from depositing the homepage image (a) above.
+
''' 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
-
(c) Write a ~95 char tweet on the paper for Mark, including bits of the title and your twitter handle/name; you can include an image too. Examples: [https://urldefense.proofpoint.com/v2/url?u=https-3A__twitter.com_markgerstein_status_789117961843900417&d=CwIBaQ&c=-dg2m7zWuuDZ0MUcV7Sdqw&r=e3g5MXVeiXZuf60bhhzWoOI0FMwKqm-QmSMQiL1sQ-U&m=IaQfwVJNTOGZFc6xlJCQoT9slGbbS4jfjsREMorjhaA&s=grRaV42K861C41-Aff3H7frn8UIdQoDFl6H29ujeHMQ&e= here] and [https://urldefense.proofpoint.com/v2/url?u=https-3A__twitter.com_markgerstein_status_790695004951961600&d=CwIBaQ&c=-dg2m7zWuuDZ0MUcV7Sdqw&r=e3g5MXVeiXZuf60bhhzWoOI0FMwKqm-QmSMQiL1sQ-U&m=IaQfwVJNTOGZFc6xlJCQoT9slGbbS4jfjsREMorjhaA&s=mDOLFVXInC_7jfP8RPySCsfwGWwhOqAJc1YzvUk2M1Q&e= here]
+
* 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.
-
== 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.
+
''' Revision History'''
-
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.
+
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 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.
+
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.)
-
== Update Apr. '14 ==
+
== IDs & File conventions ==
-
Ideas on [[File Presentation for Revised Drafts]]
+
* 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, [ftp://selab.janelia.org/pub/publications/Eddy01b/Eddy01b-techreport.pdf] 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).
-
== Revisions ==
+
* 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 [http://wiki.gersteinlab.org/labinfo/index.php/Papers_page_and_e-print_directory papers page]. Try to separate this ID with a dash or dot ("-" or "."), not an underscore ("_"), as this helps with searching.
-
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.
+
* 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.
-
* Track Changes
+
== Optimal Situation and Example Format ==
-
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.
+
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 :
-
* Revision History
+
* Word doc with the current version
-
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.)
+
** 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
-
== IDs & File conventions ==
+
* 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.
-
* Word & PDF
+
* Put a PPT (preferred) or PDF of the figures saved in the sync dropbox
-
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, [ftp://selab.janelia.org/pub/publications/Eddy01b/Eddy01b-techreport.pdf] might be a useful link. Also, please use "doc" in preference to docx as the later doesn't work with all readers.
+
** (send link to this via archive as in #1)
-
 
+
** Also put the supplement and other associated files in the sync too.  
-
* 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 [http://wiki.gersteinlab.org/labinfo/index.php/Papers_page_and_e-print_directory papers page].
+
-
* Email small files and Outbox links to bigger things
+
* 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
-
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.
+
** Do this even if you using a gdoc for the response
-
* Unique names in outboxes
+
* Unique names in drobbox
-
when sending me links to files in your "outbox" . I'd appreciate if this link be
+
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
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:
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
+
http://meetings.gersteinlab.org/2017/12.17/privaseq3-GG-121717-diff.pdf
Then you update this. Please use a link like
Then you update this. Please use a link like
-
 
+
http://meetings.gersteinlab.org/2017/12.17/privaseq3-GG-121717-diff-v2.pdf
-
http://homes.gersteinlab.org/people/joelabmember/outbox/proj1/mypaper2.doc
+
-
 
+
rather than
rather than
-
 
+
http://meetings.gersteinlab.org/2017/12.17/privaseq3-GG-121717-diff.pdf
-
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 at gersteinlab.org | 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 ==
== Comments on Parts of the Draft ==
* [[Affiliation]]
* [[Affiliation]]
-
** Way to List Affiliations for Mark Gerstein on papers
+
** Way to List [[Affiliation]] 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]]
+
* Affiliation for postdocs
** Postdocs whose primary appointment is the "MB&B Department" are also affiliated to the "Program in Computational Biology & Bioinformatics" (CBB)  
** 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.
** Hence, they can list both the affiliations. Mark would prefer CBB be listed first, but if they want MB&B can be listed first.
Line 113: Line 114:
** I suggest the following boilerplate: "We acknowledge support from the NIH and from the AL Williams Professorship funds."
** I suggest the following boilerplate: "We acknowledge support from the NIH and from the AL Williams Professorship funds."
-
== Proof Stage ==
+
== Submission and Dealing with the Journal ==
 +
* Use the pi address for the corresponding author.
 +
** Deprecated: Do NOT use [[xxmg at gersteinlab.org | 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
-
* Make sure all email addressed are "normalized" in the proof (e.g. use Mark.Gerstein at yale if appropriate and remove [[xxmg at gersteinlab.org | xxmg@gersteinlab.org]] ).
+
== [[Proof Stage Pointers]] ==
-
* Fill in grant acknowledgements with a more precise funding source if appropriate.
+
-
* Make sure you have a final URL for website materials.
+
-
* Look carefully for '''typos'''. Some are quite subtle. See http://www.biomedcentral.com/1471-2164/10/480 which then becomes http://www.ncbi.nlm.nih.gov/pubmed/19835609 and http://papers.gersteinlab.org/papers/gapdh-pgenes .
+
== First Author Common Courtesy ==
== 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.
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.

Latest revision as of 14:17, 7 September 2021

Contents

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

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.

Personal tools