technical writing

Embrace the Leapfrog

Another day, another NSF grant rejection.

Scores were E, V, V, V (E=excellent, V=very good). I haven’t seen the report yet, they probably won’t show up till next week.

The scores are only a little better than last year, although I thought the proposal itself was MUCH better than last year.

(Update: Did get the reviews, really very positive. Still no dice.)

Oh, well. Off to lick wounds and edit a student’s paper.

To that end, some levity.


(Middle Boy says he came up with these on his own, but he might be fibbing.)

Joke 1: Germanium, nickel, uranium, and sulfur worked together on a science project. It was GeNiUS!

Joke 2: I was going to work on my science homework, but then I thought, “NaH…”

(He drew a box around each symbol, like in the periodic table, with Na saying sodium and H saying hydrogen).

By the way, Middle Boy is 9. The Nerd Force is strong with the young one!


$hit my students recently wrote in drafts of technical manuscripts:

Point 1 is no secret

One of the first orders of business  was to determine…

This is surely the handiwork of [a physical phenomenon, i.e., something decidedly without hands or the ability to come up with evil plots]

It is possible to judge… using the squint test, squinting at thousands of plots is tiring on the eyes…

and my favorite

[B]y embracing the leapfrog nature [of an explicit algorithm for solving partial differential equations]…

Clearly, this (rough, pen only) drawing had to happen:


Embrace the (giant) leapfrog!



How to Write a Manuscript Review

This one was inspired by a recent conversation in my group meeting.

Generally, the outcome of a review of a manuscript in the physical sciences is one of the following options (I am sure it’s basically the same in the biological and social sciences, and maybe even in the humanities, but I have no direct experience):

a) Accept as is

b) Reconsider with minor revisions

c) Reconsider with major revisions

d) Reject

As a referee, you will be asked to submit a report (to be transmitted to the authors and thus to be written in a collegial manner) along with a recommendation to the editor on the course of action. The recommended course of action is one of the options a) to d). Some journals offer further recommendation subtypes, such as “Accept with optional revisions” vs “Reconsider with mandatory revisions (minor)” vs “Reconsider with mandatory revisions (major)” vs “Reject and recommend transfer to another journal”.  Some have additional options for the referee, such as “I don’t need to see the paper again” or “I need to see the paper again.” But these are all nuances.

Reviews (report plus recommendation) are advisory to the editor. Again, reviews are advisory to the editor. Whether the review is positive or negative, write it so that the editor can understand what has governed your recommendation.

Each referee’s recommendation after a round of review is somewhere between a) and d). Based on these recommendation, the editor makes a  single decision between a) and d) — to accept as is, to invite resubmission with minor or major revisions, or to reject. This single decision is communicated to the authors. The authors will also see the referee reports, but may or may not see the recommendations of individual referees (depending on the field culture and journal), but the authors can usually tell from the content of the reports what each referee recommended. We focus on referee reports and the associated recommendations here.

When do you recommend “Accept as is”?

Option a), “Accept as is,” is usually not recommended by any referee after the first review unless the referee doesn’t give a toss. (It’s okay to “Accept as is” after the first or second revision.) As an associate editor, when I get an adulatory but shallow one-liner after the first review, “This paper is great, publish as is,” I roll my eyes. Such a report is completely useless. It offers me no advice, other than the advice that you as a reviewer didn’t take your job very seriously. Don’t be that reviewer. If you like a paper, your one-liner will not help against a scathing three-page report of another referee who hated the manuscript. If you really like the paper, give the authors something they can use to fight for it.

When do you recommend “Reconsider/accept with minor revisions”?

When you generally like the paper and its conclusion. You think the study is correct, the figures are clear, the conclusions are supported by the data, and the paper is written well. You were able to follow what they did and how, and you have enough information to determine that the technique is appropriate and correctly applied. The minor revisions are usually: missing relevant references (a small number), minor instances of unfortunate wording, some minor tangents that would be interesting to address as they link the paper to the broader field in a way the authors didn’t consider, clarifications in the title or abstract or intro, other clarifications of specific pieces or wording or details in the technique (experimental conditions, theoretical parameters), minor corrections to the figures (e.g., recommendation to choose different colors for better contrast in a 3D plot). Basically, the paper would not be awful to be published “as is” but it could be improved to full awesomeness with edits that are not overly time consuming.

When do you choose “Reconsider with major revisions” vs “Reject”?

Is there plagiarism/duplication of work? If yes, reject, and provide references where the overlapping work has appeared.

Is the paper topically inappropriate for the journal? If yes, then reject, and explain briefly why it doesn’t fit (these are often caught by the editors, so the paper is desk-rejected).

Is the paper not hot enough for the highfalutin journal? If the answer is affirmative, then reject, but please please explain why you think so. A negative one-line review is just as useless as a positive one. The editor can’t do much with your “gut feeling” that the paper is not cool enough for the journal, especially if that’s your only reason to reject the paper. (Unfortunately, what the gut of famous Prof. Greybeard has to say seems to have more weight than the opinions of younger guts). Your gut feeling should in principle be translatable into human speech, such as: all the references are old and there are no new ones, so this work is not timely enough for this journal; most of the references, especially recent ones and/or the ones with similar work, have been published in this other journal instead; the results are straightforward extension of published work and thus of very limited novelty; the results require unrealistic parameters or only occur under a very narrow set of conditions and are thus likely not robust, etc. [see comments for differences among fields].

Are the methods without a doubt inappropriate to address the problem at hand? Then reject. But if the method is one of several and is just not what you would use, that’s not a good enough reason alone to reject the work. Different methods have different strengths and often reveal different facets of the same phenomenon.

Now we come to the tough region.

Is the paper correct? Are the methods appropriate? Is it timely? Is it interesting? Does it present something novel about the world that is not obvious?

If the answer to all these questions is yes, then ask yourself if you can envision this paper being edited so as to become publishable. What would the authors have to do, specifically, to make it suitable for publication?

Does the language need considerable attention? Is the discussion of the techniques/methods unclear? Are the conclusions unclear? Can you write down what specifically is unclear?

If the answer is that you just hate all of the paper, that it’s boring or just awfully written, or that the necessary chances are comprehensive, pervasive in every aspect, then please reject outright. Try to to explain that the paper is far from publishable and that you cannot imagine it becoming publishable within the span of 1-2 revisions; that it would essentially have to become a completely different paper instead because of simultaneous issues with presentation, conclusions, figures, etc. It is much better to reject outright than to 1) torture yourself to try to list all the things that are wrong, 2) make the authors spend a lot of time entering those edits, only to 3) find out that even after all these edits you still think the paper is awful. Rejecting a paper because of pervasive issues is a kindness. For instance, imagine if you were to submit a first draft of a paper written by a second-year graduate student. These drafts usually require extensive edits and the advisor has to make several (many?) layers of corrections in order for it to become suitable to unleash upon the world. Similarly, there is no point in wasting the time of multiple referees “editing by peer review” something that’s as far from publishable as an early draft of a newbie student.

So, when do you say, “Reconsider with major revisions”? When you can envision a finite number of specific things that the paper needs in order to become publishable. Imagine receiving the paper with those revisions perfectly incorporated; if you would then have no problem accepting the paper, then that’s major revisions. Major revisions usually include: significant gaps in cited literature; missing data/figure(s) in order to support a conclusion; missing critical information that prevents a reader from following the exposition or assessing the correctness of the approach; poorly written abstract or conclusion.

How do you write a useful referee report? 

Start with a 2–3-sentence-long paragraph (Hyphen happy! Technically, the first one is a dash.) in which you state, in your own words, what the paper is about, how the authors do what they do, and what the main findings are. This helps show the authors and the editor that you have understood the paper.

Then say clearly, in a single-sentence paragraph,  what your position on the fate of the paper is. Do you feel it’s generally great, but have minor suggestions for improvement or minor but required edits? Do you think it’s inappropriate for publication in the present form, but expect it to become publishable if the authors satisfactorily address the specific problems outlined below? Or do you think the paper is simply not appropriate for publication in This Journal for reasons that are deal-breakers, and concisely explained?

If your are disposed towards rejecting, make sure you state why in a few sentences or a couple of numbered items/paragraphs.

If there are major issues with the paper, give a numbered list of major issues that the authors should address. Be specific about what you want them to do. Remember, if you are a good referee, this should be like a contract: if they do what you ask, you will recommend acceptance. Don’t be that douche who keeps moving the target and asking for new and varied things in subsequent reviews. Follow with a list of minor concerns, like the typos you caught, unfortunate wording, missing units, etc.

If you have identified minor or optional revisions, list them also in a numbered list. If something is optional to consider and you do not require that the authors comply, but just to seriously consider it, then say so.

Happy reviewing!

(See the comments for some differences between fields. Students and postdocs: your own advisor is your best guide regarding established refereeing practices in your field.)

Let It Flow — Part 2

— continued from here

Thy Paper Shall Have a Story

Papers for publication are different from proposals, and they are also different from reports or theses/dissertations. (This insight brought to you by Captain Obvious.)

Before you write a paper, you first have to ask yourself:

a) Do you know what you did?
b) Do you know why you did it?
c) Do you understand what you found?

Most students know what they did, which in a paper goes somewhere in the methods section and is often easiest to write.

However, most students, especially young ones, don’t actually know why they did what they did (other than that the advisor nudged them towards it). Why you did what you did is what makes your introduction and it is a very important part of the paper.  Often, writing a poor introduction means not really understanding where you work fits with the state of the art, which in turn means that you have to go back and read the literature more broadly, and you have to talk to your advisor more.

Understanding what you found goes into the results part of your paper. That’s “the meat.” Students have an easier time writing the results than the introduction, but often I find the results to be written trivially, just reading trends of graphs. That’s generally not enough for any reputable journal.

Your paper has to tell a story. It needn’t be the world’s most complete story, but it has to have a beginning, a middle, and an end. In other words, it has to have the Why (Intro), the How (Methods), the What (Results), and the So What, a.k.a. how it all fits with what we know or don’t know (Results/Conclusion). This is the paper skeleton, and it’s a good idea to not start writing the full paper until you are comfortable with it. (Again, you and your advisor should be talking about the skeleton  several times.)

Once you really truly understand the why, the other parts are easier to write. The intro needs to connect between setting the stage for the reader to recognize where your field is and what the important open problems are, what you do to address an open problem and how, and what you found and why it’s important.

Introduction (each of the paragraphs can be more than 1 if lots of material)

Paragraph 1: Open with an overview of the state of the art in a broader area and perhaps note applications relevant for your paper.

Paragraph 2: Recent developments in a closely related subarea; what is known (who measured/calculated it), what is still being debated (who said what, if there are competing experiments/theories)  or what is relatively open (any relevant work, perhaps on related systems), and why it is particularly important that we find an answer to some of those questions. (This paragraph also mentions briefly, some of the common experimental or theoretical methods, as you discuss the work of others).

Paragraph 3: “In this paper/letter, we…” State concisely what you did. It needs to connect to the open problems you just discussed as important in the previous paragaph. State what you did, how, and what you found, and how it answers the question(s) posed in Paragraph 2.

Paragraph 4: When writing comprehensive papers in the physical sciences, there is this “Table of Contents” paragraph, where you say things such as “This paper is organized in the following manner. In Sec. II, we present the methodology, …” Many people keep it entirely generic (Sec. II Methods, Sec. III Results, Sec. IV Conclusion), but I like to put in more detail and use this paragraph to show how the main thread connects my story (“In Sec. III A, we show the vibrational properties of vibranium obtained using neutron scattering experiments… In Sec. III D, based on numerical simulation, we reveal that these unique mechanical properties of vibranuium make it an ideal material for intergallactic warfare.”)

The Vomit Draft

The whole paper — the material you put in and the order you put it in — is in the service of presenting your story.  The story should be reasonably clear in your head before you start writing. However, sometimes, after you start writing, you actually go and look some stuff up and think of things another way and, all of a sudden, you may need to change parts of the story somewhat, or even dramatically. This is natural — it happens in technical writing as well as in fiction — and is perhaps the most fun part of writing: the fact that writing helps clarify your thinking. Which brings me to the common saying that you make figures first, then write around the figures; this is true enough, but is hardly gospel. I say have a skeleton first, a decision on what the paper will be about (informed by dozens of figures you and your advisor already went through before writing), then make the figures to best support your story, and then write the results section around the figures. My students and I redo figures many times during the writing-editing process, as we distill our message.

However, you have to start somewhere, and that somewhere is a reasonably clear concept of your paper’s story. (Sheesh, have I said it enough times already?)
Then you start writing a rough draft, also sometimes colloquially referred to as the vomit draft, because it hints at people vomiting the inside of their heads onto the page; like vomit, the product is generally misshapen and not pretty, but is usually not smelly. [If your vomit draft actually smells like vomit (eeww!), stop spilling food all over your keyboard. You are gross.]

Now, I know there are folks in the blogosphere who will tell me that some people don’t write the rough draft but their sentences come out their heads perfectly formed right away. If you are like that, more power to you, you are a freakin’ unicorn — I bet the horn focuses your thoughts! However, most people need a rough draft, which they then edit, and for them it’s good practice to separate writing as things come to mind (which helps with the flow) from editing (which ensures that horrible grammar, spelling, and punctuation are not unleashed upon the world, or worse — your advisor’s desk!).

So, with a clear outline of the main story in your head, just start typing things as they come to mind, as you would tell them to another person. Imagine yourself giving a talk… unless giving a talk is even more terrifying than writing, in which case imagine you are on a beach, in a hammock, talking to a really hot hammock neighbor about your research project over some margaritas. At this point, please don’t worry about grammar at all. Just write how you think about your story.

A trick that helps is to start writing amidst a block of already existing (unrelated) text, so the whiteness of the page isn’t daunting. I always cite Finding Forrester and how Forrester helped his young protege by having him type on top of an old story. This trick has helped many a student. In my group we use LaTeX, so everyone starts learning LaTeX by working from someone else’s paper anyway, which provides examples of LaTeX commands and of semi-related existing prose wherein you can nestle your draft.

The point is to start; once you start, just dump the contents of your mind onto the screen. Write as things come and, as long as words pour out of you, don’t stop… unless you are starving, have a bladder that’s about to burst, or can barely keep your eyes open; in any of those cases, please stop; you will be able to get good flow later, I promise. I hate it that in the popular culture the ability to write is conveyed as some sort of mystic, hard-to-replicate experience (and nobody ever shows editing); a recent offender is the movie The Words I just saw on Amazon Prime (the movie is so-so otherwise).

Don’t worry about “the muse” in technical writing. You will get good chunks of text out of you on multiple occasions. Just write. It needn’t be pretty, it needn’t be super organized, just write. Consider it a chance to reveal your thought process and your knowledge and your excitement to other scientists. The more you write, the lower the barrier to writing.

Edit later

But when is later? When the flow stops. When you are done with a few paragraphs. When you are having a hard time getting the flow started. When you are almost done. When a few days has passed since you finished a draft. When office mate asks you to look at their paper. When it’s either edit or check references. Basically, don’t edit at the level of every word or every sentence you produce, but you can do it paragraph by paragraph or page by page or section by section, depending on personal preferences, available time, and editing stage.

Good editing means careful reading, putting yourself in the reader’s shoes, and — more often than not — murdering your darlings, so your other darlings can go on and get reviewed well at a fancy journal.

Don’t be afraid to let some grammar rules slide if they ensure good flow: e.g., sometimes long sentences are justified and work better than shorter ones, which can be choppy. Don’t be afraid to use punctuation in the service of your point: I use commas, dashes, and parentheses, which can all help separate a minor clause, depending on how closely it’s tied to the main clause. I love the semicolon and use it a lot in technical writing; it provides closer coupling between successive sentences than a period. Things like that. (Sadly, ellipses and exclamation points are not welcome in journal papers.) Proper punctuation will help pace your reader.

What say you, blogosphrere? These were lengthy posts, so I am a little (okay, a lot) out of steam, and I am sure I forgot a whole bunch of things. Please let J know what your favorite tricks for ensuring good flow in technical writing are. 

Here are also links to related posts on Academic Jungle and here on xykademiqz

Happy vomit-drafting! 

Typesetting Grant Proposals

I am in a physical science field, addressing problems by means of theory and computation. I also work a lot with experimentalists.

When I write paper or proposals with experimental colleagues, since they all use MS Word, I use it too. I also use MS Word for a lot of small documents (writing homework assignments and tests, letters of recommendation, all sorts of administrative documents).

On the other hand, I write papers with my students exclusively in LaTeX. The students’ dissertations, which are largely based on their published papers, are also in LaTeX. There is really nothing like LaTeX for producing beautiful documents with a lot of math. And, of course, the publisher that is of greatest interest to physicists (the American Physical Society) prefers it — the beautiful REVTeX two-column template (REVTeX is a collection of LaTeX macros) is the gold standard of preprints, widely recognizable as the “template of the true physicist” (see arXiv, for instance).

I also write a lot of proposals by myself. This year is worse than average in the number that I have to submit. In the past, I have written grants in MS Word and I have written grants in LaTeX. And I have a confession to make: of late, I have been writing my grants in MS Word.

Grants are complicated documents, often bridging between disparate bodies of literature; they generally have strict formatting requirements and very high standards for readability and flow. Every grant writer will recognize the need to use the available page are efficiently, without cramming too much or wasting precious space.

LaTeX, in general, will let you format the document as you see fit, but will do so grudgingly. It always knows better than you what looks good, and it generally really does; it incorporates the best typographic practices, as it was meant as a tool that lets you focus on content while not dwelling over layout. However, writing proposals is where you need to have it your way because of the spacing requirements. I have lost a lot of time in the past wrestling with LaTeX to have the wrapped figure where I want it and not where LaTeX deems it appropriate, trying to reduce the white space around the figure etc. Also, excessive math (or virtually any math) has no place in proposals, even theory ones (typesetting math is what makes Latex superior).

While it doesn’t bother me in the least that I have to compile in order to look at the text when I write a paper, it bothers me a lot when I write proposals. The proposal is a work of both form and substance, in which text flow and layout are critical. Also, proposals are usually written (by me and the likes of me, at least) on a very tight schedule, and I find that just having one document that I can easily scroll down or up alleviates some of the tension. In contrast, when I write a  proposals in LaTeX, I usually have a master file and separate files for different chapters/sections  (which makes it easier to track content and edit), but — in the mad dash to the deadline —  working with source files in Latex  makes me feel disoriented and interferes with my work flow and thought process; none are good in a time crunch. So I go with the WYSIWYG MS Word.

So, yes; I am ashamed to say, these days I use MS Word to write proposals. *hangs head in shame, turns in physical scientist card*

I am actually a little worried about being judged for writing a proposal using MS Word instead of LaTeX during proposal review (the one I am writng now, in particular). There is a lot of “one true path” among scientists, from the choice of the operating system [e.g. real computational scientists would not use anything but Linux (Mac is acceptable, but Windows is only for the dimwitted)]  to programming language or any piece of software. I review a lot of proposals, and the ones from pure physicists, especially theorists, are usually written in LaTeX (with its recognizable Computer Modern Roman, a pleasantly plump font). I am seriously worried that my use of the Text Editor of Pure Evil will immediately dismiss me as not being a real scientist in the eyes of some who may review this particular grant. My husband thinks I am nuts for worrying about such things; of course, you’d think that the content of the proposal is what matters. But we all know scientists can be territorial, petty, judgmental, and dismissive (you know, just like other humans) and it is not inconceivable that I might be looked down up because of the non-LaTeXness of my proposal (not like my femaleness, apparent from the proposal cover page, will do much to help). Then again, it may be the nerves talking. I do tend to lose my belief in humanity and become more misanthropic than usual at proposal crunch time.

What say you, esteemed blogosphere? How do you typeset your proposals? Do you care about how people have typeset their  proposals when you review them? 

Random Bits of Technical Writing

* I am working on a paper that I think has the potential to be a really big deal. It’s so awesome! I am so excited to finish it and submit it that I literally can’t sleep. I sometimes (probably more often than I care to admit) feel like I’m falling in love when it comes to papers or proposals, with butterflies in the stomach from all the anticipation. I can’t get my darling paper out of my head, I keep thinking of the softness of its curves, the color of its data markers, the size of its axis labels… *sigh* …Maybe I need a cold shower.

* There is a colleague whom I met a year or so ago in person, but whose work I have known for a bit longer. His work is technically good, but the papers are not. For some reason, he just can’t write a compelling  narrative or choose the best examples to support the premise. Whenever I read one of his papers, I am thinking — dude, you could have done so much more with this, and there’s always a let-down, a feeling of disappointment when I am done. In the past year or two I have received several of his papers to review, all in lowerish-tier journals; obviously, I am on his preferred-referee list. The first N times (N=3 or 4) I accepted, then tried hard to give detailed constructive advice and feedback. But recently I received his paper N+1, I looked over it and I just couldn’t do it. It’s bad, it’s too little, and the figures look awful. I don’t have time for this, so I declined to review. I would like to help, but I don’t think I am helping through constructive refereeing. He would really benefit from some serious coaching, but he’s not my (or anyone else’s) student or postdoc. I am not sure what to do, probably nothing.

Riff-raffin’ It

A lot has been written around the scientific blogosphere about some prominent gentleman of science lamenting the fact that science today is populated by riff-raff as opposed to the intellectual giants among whom he undoubtedly counts himself. I am not in the mood to retell what was already covered elsewhere, so if you are interested go ahead and check out these links (here here here and here)

I have a somewhat related riff-raff story of my own.

Some time ago, I was nominated for a university award, which is very competitive and several letters of reference are required. I suggested the names of several colleagues, all senior to me but not dramatically (perhaps 5-10 years). I suggested them because I know a) they are serious scientists who do good work on topics close to mine, b) they follow my work and would be able to write about it in detail, and c) they would be willing to write these letters for me because they think I am a serious scientist who does good work, too. These colleagues are from all over the world.

It was brought to my attention that some of them may not be not high-profile enough to write letters for me for this internal ward.

I felt a little offended on my colleagues’ behalf. First, they are excellent people and some of the top people in our relatively small field (not small for a physical science, small when compared to most biomedical fields, for instance). Many of them are in Europe, where getting a full professorship is much harder than in the US (basically, a chair has to become vacant). Many of them don’t care about the accolades the way we do in the US —  for instance, even some very prominent people never bothered to become fellows of the appropriate professional societies, even though I am sure they would be shoo-ins. Lastly, most of them, being outside of the US, don’t maintain meticulous professional pages with awards and honors; for all I know, they could be drowning in awards, I wouldn’t be able to know without point-blank asking.

First of all, this was a competitive but ultimately university-level award. I wanted to ask people for whom it would not be too much of a stretch or effort to write about my work and whom I would be comfortable asking because I believe they wouldn’t mind doing it for me. I must be riff-raff myself, as I don’t rub elbows with MIT or Stanford folks; I do know people in these places (and god knows I send them enough grad students with REU experience and awarded NSF fellowships; where are my brownie points?!) and I will bother them when the time comes to write letters for my inevitable second Nobel prize. But for an internal award? Not so much.

Why is it that whom you know and who vouches for you are  the most important proxy to scientific quality? And why is it that a select few get to have an opinion about everybody’s work ? Surely the opinion of someone who doesn’t follow your contributions at all because they do barely related things cannot be more valuable than that of someone who does follow it? Why does being at Elite U endow someone with superpowers to judge everyone everywhere for everything?  If only a handful of universities are worth anything, why not close all the other ones and be done with pretending that there is important science elsewhere? We who are not at Elite U give them that power.

There are kick-ass riff-raff people everywhere. They are smart, curious, respectful to colleagues, and they they make doing science fun. They are my riff-raff.  Don’t anyone dare say anything bad about them.

To wrap up on a cheery note, here is good cheap wine that DH and I have been enjoying lately. Apothic Red — it’s great, and about $8 per bottle at Costco. (I do not recommend Apothic Dark.)