Paper writing tips

• Style
• Admin

This a checklist of sorts for people working on papers with us; there are rare cases where one can make a thoughtful and justifed exception. In other words, draft manuscripts should have addressed these issues before they're given to others to read for efficiency. Time permitting, I prefer a page numbered, double spaced, document written using LaTeX which we can edit using Overleaf (so ask me to create the initial blank draft for you if you don't have a paid subscription since it allows for track changes). Please highlight all changes you make between iterations, especially those you make of your own accord without my input, using the \editauthor macro.

I also have these scripts, ~usr/grants/bin/check_all and the contents of ~usr/grants/etc/check/ for specific direction. Also, if you really want to get this all right, get A Handbook for Scholars by Mary-Claire van Leunen. Some of the finer points are illustrated in this pet peeves URL (with suggestions in LaTeX on how to address them).

Style

• Write to convey excitement. To do this means going against a lot of instructions on how scientific papers should be written, but I personally dislike overuse of the passive voice.
• Make sure every sentence is as crystal clear as possible; each sentence should convey exactly what you're trying to say.
• Be terse. Say what you want with as few words as possible. Try not to overuse punctuation marks. For example, a sentence of the form "We will perform a continuous sampling technique that is superior to conventional grid based techniques." instead of "Rather than using conventional grid based techniques, we will use a continuous sampling technique". The first sentence is more clear, simple, and straight forward.
• Do not have tables and tables of numbers. All tables should be converted in descriptive figures, and the table should be made available as supplementary material. It's rarely necessary to use more than 2-4 significant figures; use the minimum number of significant figures that you need to convey the message.
• Always concisely summarise the message of your tables and your figures at the end of their captions. This should be done so that someone seeing only your tables and figures should be to able to understand your entire paper. In general, the structure of a figure or a table should be: A concise title explaining what is being shown; any details absolutely necessary to understand the figure/table, but no more (definitions, etc. can be left to the text); and a summary sentence containing any conclusions (usually for results).
• Grammar and proofreading should be a given. If you have trouble, ask someone to do it for you again and again (and if someone complains about doing this, let me know). We're all here to help each other out. Do not attribute actions to inanimate objects (anthropomorphise): for example, "protein's structure" should be "structure of a protein". Also, "which" is not always appropriate for inanimate objects (i.e., "a protein that is used to" as opposed to "a protein which is used to").
• Do not use "In order to...". "To" is adequate.
• Do not use "x axis" or "horizontal axis" when describing graphs. Just say what is plotted against what.
• Avoid widows and orphans (i.e., single lines or section headings by themselves on a page).
• Consistency is important. Some issues I've come across so far include:
  • When you first use an acronym, first write out its full name as it is commonly used; for example: "Critical Assessment of protein Structure Prediction methods (CASP)". You may choose to repeat it for every large section you have (i.e., results, methods, etc.).
  • English vs. American spelling. I use English spelling and most of you use American spelling. It doesn't matter what we use. If we submit to a British Journal (including Nature and JMB) the manuscript will adhere to English spelling and will be changed accordingly. If we submit it to an American journal, it will be American spelling. The final draft of a manuscript should have consistent spelling (either English or American--the typesetters will get it right).
  • Consistency of tense. If there's something that generally holds true always (i.e., "Contacts are compiled from a set of known structures in the PDB"), then it may be better to not use the past tense. Generally, when talking about a methodological description (say of an implementation) that everyone who reads your paper has to do, present tense can work. When you're talking about an experiment you did, past tense is better.
  • Hyphenation. There is generally no need to hyphenate most words. I've realised that stating "well characterised" is as communicable as saying "well-characterised". So for consistency's sake, it's better to not use hyphenation whenever possible. Please check this as you write.
  • Use of numbers as letters or digits: The old rule used to be that anything less than or equal to twenty should be written as a word (since it's a single word up to that point). Anything else is written as a number. This doesn't always read well aesthetically. So a slight modification to this rule is that if you're enumerating something (6 compounds, 10 structures), then use numbers. If you're just referring to a few items (like three studies), then you can use a word, along with the less than equal to twenty rule. There is no automated solution to this problem and it really does depend on context a lot. Do not start a sentence with a digit.
• Our group is a "group" not a "lab" or "laboratory".
• As everyone knows, I keep saying writing is the currency of academia. I also say every sentence has to be perfect, but I'll settle for near perfect. Even the most excellent writers among us have to undergo several iterations before a manuscript is considered complete. I am proud of say many of you have learn to write amazingly well in the time you've spent here. Keeping this general, the point of writing is to communicate, not to please your mentor. If the mentor makes a correction or a suggestion, the point isn't to make the mentor happy (in general the mentor knows everything you're writing about), but to make your general audience happy. Some of you write for the sake of this clarity, to TRULY communicate, and some of you write reluctantly and to satisfy comments made your mentor, reviewers, and editors. This is not how it should be --- writing should be fun and enjoyable, like science (you can discuss with me personally if you have insecurity issues here about your own writing and where you stand but if you can write a program, you can write papers even better :).
• Every statement you make should be tailored towards an inexorable trajectory (of presenting your overall message).
• In the end, writing is an iterative review process. You have to keep going back and reediting until you feel it has reached perfection. A single change usually isn't going to do it.

Admin

• When it comes to authorship, be liberal in your inclusiveness rather than conservative, when listing the authors.
• Make sure all grants are properly acknowledged; again, be inclusive rather than exclusive.
• If the journal does not require it, a section on individual author contributions should be included in the acknowledgements section.