Revision as of 17:50, 22 February 2022

Regardless of the kind of publishing below you wish to undertake, please be sure to read our style suggestions in detail.

General

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

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

• We do computational science, i.e., computational experiments that are well designed and rigourously controlled in a computational laboratory. Our group however is just that, a "group", not a "lab" or a "laboratory". Write with this in mind. So I use the word "wet lab" or "bench" but "wet lab" is probably best when referring to wet experimental work.

• 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 to say many of you have learned 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. So please plan your writing with this in mind, giving us ample time to go back and forth on the editing

Choosing a journal

Start by browsing journals in the field. If you don't know, start browsing names in the field, find journals from there, look at titles and abstracts, find papers you like, check if the figure size, length, etc., "feel right". Write the paper first and then decide where to send it after it is written and then reformat. Its best not to think about the very specific journal it should go to (a class is fine, like a bottom tier, mid tier or high tier) until the paper is fully formed. It makes more sense to evaluate then.

You should go for the highest impact factor possible: ISI Journal Citation Reports (eigenfactor is also used). The range of audience to whom you can write is pretty much the first filter. The next filter is the focus of the journal (both ~mission statement & the types of papers they publish), this pretty much describes the intended audience of the journal. In the end the relevance of the qualified reviewers to the journal is a tangible cutoff - who is actually going to review this thing, and how would the Editor of Nature Genetics feel about trusting their opinions?

Structure of the document

• Have a consistent, clear, and concise structure. People follow logical writing more easily than unstructured writing. This means grouping things into appropriate paragraphs, with clear and concise headings.

• For journal publications consisting of original research, the structure is usually an abstract/summary, and introduction that provides background, a methods and materials section (which these days tend to go towards the end), results, discussion, and conclusion. In many cases, the research and discussion can be combined into a single section. Sometimes the discussion and conclusion can be combined into a single section. Do what makes sense for the particular publications. Reviews, book chapters, and other types of publications will have a slightly different structures, but the general idea is always the same: summarise the whole work, provide appropriate background, describe how you did what you did, what you did, why you did it, and what it all means.

• Start by providing a summary of the entire work. This abstract/summary should not be an introductory paragraph (that leads into the introduction) but rather a sumnary of the whole paper that stands on its own. Each part of the abstract (could be a sentence or two, but no more than a few) could be thought of as describing as a section of the publication. So you could have a sentence that describes the entire introduction, and a sentence each for how, what, why, and the meaning. This would be the most terse form of the abstract.

• The abstract is one of the most important pieces of a document. Reading it alone should be enough to understand what is going on in the paper. But to convey complex ideas, figures and tables are usually necessary. Each figure and table should follow the same guidelines as given in the rest of this document (i.e., should be terse, clear, and consistent; all figures and tables should have the same look and feel; avoid typographical and grammar mistakes, and so on). Every figure and table caption should have a concise summary sentence in bold, followed by a detailed explanation of what is going in the figure, and finally a concluding sentence that serves as the bottom/punch line to figure that describes what it all means. There should be no deviation from this structure of captions unless the publication type warrants it.

• The abstract and the figures and tables and their corresponding captions should be adequate to understand the entire publication. Keep this in mind while doing these items, particularly the captions. The captions shouldn't just describe what is in the figure/table but relate it to the rest of the publication such that together with the abstract, the work is fully understandable.

• The introduction should provide the background and in general should be scholarly peppered with all the necessary references for supporting the rest of what you're writing.

Technical issues

LaTeX references

If you are writing something with me that is in LaTeX (such as a grant application), please send me your references in BiBTeX format. See ~ram/src/tex/bibtex/all.bib for examples of the format and see ~ram/src/tex/abbrev.bib for the abreviations (acronyms really) used for the papers. You can create a file called add_to_all.bib of only your references and add_acronyms.bib that contains the new acronyms/abbreviations that are not already present in the main acryonyms file and put them somewhere and point it to me. If there are no acronyms/abbreviations, make one up using the first letters of the shortened name given when you search PubMed.

Authorship, credit, and acknowledgements

Authorship and credit

Credit in science I believe flows naturally. In other words, do great science, and the rest will follow. There is, I've noticed even among very bright people, a tendency to get too hung up on authorship, credit, and acknowledgements devoting excessive energies and causing unnecessary drama when those energies are better expended on doing the science itself and saving the drama for when it is needed.

At the same time, these are important issues and we believe that how a group handles these issues should be set out in the open for others to evaluate and to permit refinement. While other institutions and associations have their own author guidelines and suggetions, we have our own which is based on fundamental principles of openness, transparency, expansiveness, inclusiveness, and fairness (Kantian ethics, the Golden rule, and its contrapositive). The general philosophy is similar to what Jonathan Postel once said about the Internet protocol (TCP), to be conservative in what we do, and be liberal in what we accept from others. We believe that every authorship situation is unique and for a manuscript, it should be decided on a case by case basis. Our suggestions here are meant to be somewhat detailed since the aim is to make our ideas transparent so people can decide whether this is the right kind of group and environment for them. Make no mistake that we walk the talk.

• When it comes to authorship, be liberal in your inclusiveness rather than conservative, when listing the authors. As many great people including recent ones such as Albert Einstein have said, we are able to do worthwhile things because we are standing on the shoulders of giants who did worthwhile things.

• Make sure all grants are properly acknowledged; again, be inclusive rather than exclusive. Don't be afraid to ask!

• Regardless of whether a journal requires it, a section on individual author contributions should be included in the acknowledgements section.

• If the journal needs a cover letter, or if you will be writing one, please be sure to give me a draft of the cover letter near the final stages of editing.

• In general, the principal investigator is typically the corresponding author of all work that goes out from that investigator's group.

• Our group mailing list archives have extensive discussion on this topic.

Acknowledgements

As of 2011, anything that remotely has Ram's name on it should acknowledge the Pioneer and CAREER awards (they both recaptures a huge chunk of my salary by mandate, which is a minimum of 51% FTE for the Pioneer). The same applies if you're using the new farm machines or any of the new computers or other resources. If you did the work in the last 5 years please also acknowledge my CAREER award which ended last year. In general you should acknowledge all sources of support that contributed all or in part to your work. This is very important since these guys have given you money and even if you worked for only a month (let's use that criterion) with that suport, it deserves to be mentioned. This includes some of the REU fellowships from NSF, Mary Gates awards, and other small grants.

You can write: "This work is supported in part by a 2010 US NIH Director's Pioneer Award (DP1OD006779) and NSF CAREER Award (0448502) to Ram Samudrala". (Or "RS" if the use intials, or you can omit "to Ram Samudrala" if that's the convention but normally you name who a grant is given to.)

Please do NOT forget to do this.

Please also acknowledge all the people who help you for a paper, poster, etc. You can write something like: "The authors thank George White, Ling-Hung Hung, and Haychoi Taing, as well as the entire Samudrala Computational Biology Group, for valuable discussion and technical assistance."

Look at our past papers to see how we acknowledge historically. As the group gets bigger and as we write more, I might not have time to police everything. So it's up to you to get this important piece of the paper right. ALWAYS over acknowledge than under acknowledge.

Grant applications

See Documentation:Grant applications.

Use as checklist

Regardless of what is being written, this page, along with the Documentation:Styles may be used as a checklist for our group when they writing something (scientific manuscripts, posters, web pages and sites); there are rare cases where one can make a thoughtful and justified exception but they need to be made before sending me the publication. To be clear: I need draft publications that have addressed the items in the checklist before I read them. So please, especially when working on a paper or a grant application with me, treat this as a checklist and go over each item one by one and check it off if you think you've addressed this in your publication, before sending it to me. Many of these items are trivial and you may wonder why I obsess over something trivial, but the problem is that I am swamped, with little time, and I am in constant demand to read and review many publications for people (beyond our group), and I dislike addressing these issues again and again with every new person or manuscript.

This is largely focussed on writing. Time permitting, I prefer a page numbered, double spaced manuscript which I will correct by editing directly and/or by comments or some combination. Then when you give me the next iteration, please include the old version too. When you do this, please highlight all changes you make between iterations, especially those you make of your own accord without my input.

Please also send me the BEST possible draft at any given time rather than expecting me to read through something with poor spelling, grammar, etc. since I unfortunately do not have the ability to see past them.

Please also look at /home/ram/usr/grants/bin/check_all and the contents of /home/ram/usr/grants/etc/check/ for specific issues. 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).

CompBio wiki (CompBiki)

Even though this is a free for all wiki (if you are a group member) the same as our group (i.e., a structured anarchy), there are general style and content suggestions that you should be following that applies to anything to you write. The rest below are style suggestions specific to our CompBio wiki, or CompBiki.

Feel free to organise your research in your personal page, by topic and by the kind of information you are displaying. You can put your weekly reports here or items you can point to in emails to the group (emails will grab more attention that repeatedly loading this Wiki and hoping someone has read your request for help). If you've not guessed by now, our group is funny. Plus we don't care if you laugh along, or with, as long you laugh. Anything that puts the camaraderie of our group on display, particularly geek humour, is welcome.

On the more serious side (already?), we are also a critical and rigourous group and while we needn't read this Wiki as though we're reviewing a manuscript or a grant (though some of us probably will), everyone may feel free to correct anything from minor typos to major boo boos. Do your due diligence however, otherwise your corrections are what might get corrected. You can literally have this literal anarchy since every single byte you submit is stored for perpetuity and all edits are completely reversible. So don't panic if you suddenly see your Bio page that you so painstakingly worked on has been vandalised. Not only can this be reversed, but it can also be corrected by you! No need to go to root anymore.

So you can treat this as a sandbox you see kids play in at your local park. You can pretty much do what they do, as long as you remember all the politically correct rules and regulations society has placed on you as/if/when/while you grow up (unlike our "suggestions").

Write according to the style guides please. Discussion ABOUT the issues in a wiki article can be on the discussion page. If you disagree with a note/section written by someone else, then don't edit it with your disagreements embedded in there but rather start a new section with proper headings (you could give what the other person has written a heading and give your opposing theory a heading and others can discuss that). Please make sure you use/keep the labels to characterise each type of page (i.e., "Documentation:", "Discussion:").

Okay, so onwards with some specific suggestions:

• Use a person's name username instead of their name (enabling easy reference to their member page, if they have one).

• Avoid external URLs within a document, and try to make it as self contained, as much as possible. By this links to other documents within CompBiki are definitely cool; links to other documents within the CompBio web sites are moderately cool; and links to the outside Web, well, it's a fragile one we have.

• See the Documentation:publications for even more suggestions on how to present written work. We obviously feel the more well you write damned be context, for the better it is.

• For formatting publications, please be sure to use the same format used for our publication list.

Security

Do not use the same password for the Wiki as you use for the CompBio network!

Adding a page to a category

To add a page or uploaded file to a category, simply edit the page and add the following text (where NAME is the name of the category you want to add it to).

[[Category:NAME]]

For example, to add a page to the Group Documentation category simply edit the page and add the following text:

[[Category:Group Documentation]]

Also note that any page can be a member of multiple categories. This feature can be used to create subcategories. For example, a page pertaining to a talk given by a group member would be in both the "Presentations" and "Oral Presentations" categories.

Adding/editing your member profile

All members should maintain a profile to introduce themselves and present the latest summaries of their research in the Members section.

To add your page... (todo)

File uploading and filename conventions

Please try to use this format consistently. It will help with searching and various other programmatic actions down the road. All filenames should be lowercase.

For presentations and posters, filename format is username_mmmddyyyy[-N].ext where the date is the date of the presentation (or the one closest to it) using our date conventions, and an optional -N (-1,-2,-3,...) suffix before the extension is used when multiple instances occur in the same day. For example: ram_feb032005-2.ppt

For manuscripts, filename format typically be the first author's last name, an underscore, the year with all four digits, a character identifier to make it unique, and optional manuscript type modifier(s): d - draft; f - final published version; p - galley proofs; a number to indicate the stage for a particular type, and the filetype extension. If the modifier is omitted, it is assumed to be the final published version. For example, samudrala_2009h indicates the first author's last name was "Samudrala", the year of publication was 2009, and this was the 8th file with the same string up to that point (ergo, a h was added to make it unique), and the filetype is PDF. A second example is horst_2010d24.docx where the first author last name is "Horst", the year of publication is 2010, the optional type modifier "d" indicates it was a draft and the number following that indicates it is version 24, and that the filetype is Open XML.