technical writing


I have been a slacker blogger… But for a good reason! A lot of technical writing is happening these days, making sure papers variously get submitted/revised/come out before the proposal-writing lockdown commences in August.

But there’s always time for a little rant!

If you have been reading my blog for some time, you might remember that I think one of my defining qualities is impatience. I am intense and a real pain in the butt, so says pretty much everyone who knows me. I am irritated when people talk really slowly or can’t get to the point fast for whatever reason. I have colleagues whose emails I dread receiving, because they always respond to even the shortest of inquiries with multi-screen emails and I just get queasy at the thought of parsing through all that verbiage.

I do try (and unfortunately sometimes fail) to be cognizant and respectful of the fact that not everyone has the same priorities or timelines as me. However, for my own sanity, I try to stay away from people whose relevant timescales are longer than mine by an order of magnitude or more.

When it comes to writing papers, it seems I want them written up and published more passionately than most people I work with, even when those other people are first author. That’s a source of puzzlement and irritation on my part, perhaps on theirs as well.

First of all, I love working on papers. I love doing the figures, writing the text, I love all of the aspects of organizing my thoughts into something fluid and cogent. And I LOOOVE the process of uploading and submitting a paper. It’s like Christmas morning every time. I felt this way even when I was a student.

These days, my students do the uploading and paper tracking for the most part. I consider it part of training to learn to correspond with editors and referees, to fight for the publication of their work (I oversee and edit all the correspondence). But I almost never see in my students that crazy enthusiasm, which has followed and still does every submission on my part; it confuses and saddens me.

I wonder to what extent I and the likes of me really understand what motivates most graduate students to go to graduate school.  I mean, I understand intellectually — in my field, most people want to put in the time to get a degree that leads to a well-paying job — but I don’t think I actually get it at my very core. Many students have multiple hobbies to which they devote considerable energy and time. Graduate school seems just another thing they do, and not a particularly important one at that, or one that brings them much joy. Basically, it’s like a job. They do what they are told competently, but very little creativity goes into the work. I see very little pride about their work, very little desire to show their cool contributions to the world. This is very different from how I felt about graduate school or how I feel about my job even now, with the ups and downs and funding uncertainties and post-tenure slump. Being in grad school is a freakin’ privilege!

This post is motivated by a recent experience with a former group member (FGM) who is now a junior faculty member elsewehere. We are writing up our last paper together, one that should have been published a year or more ago, but FGM was preoccupied with job applications, then moving, getting settled into their first year teaching, etc., so I didn’t want to get on their case. But it’s time, and FGM really needs papers (I know they do, I hope they realize how much they do), yet working with them on this last one has been like pulling teeth. I did a large share of edits, a very lengthy referee response (3 referees), not to mention cleaning up the text and have recently had to redo a figure in a way that completely pissed me off because, while I love fiddling with figures, I am far too senior to do things like this (such as doing a point-by-point capture of experimental data from a graph in another group’s paper, to which we compare our theory). I was pissed because I was doing this work as I apparently wanted this manuscript submitted and done more than FGM, the person who is first author and considerably junior to me, and they were acting nearly disinterested. I have had to prod and poke them to submit every revision.

Another student told me that I am the only professor he knows who actually works on the figures themselves;  everybody else’s advisors just mark corrections on the paper and do that as many times as needed. I do go back and forth with students several times, but then at some point I need minor layout tweaks and to try different combinations of panels or colors etc. and with all but one or two students, who seem to have a naturally good aesthetic sense and are able to produce appealing visuals on their own without excessive intervention, it’s sometimes much less painful for me to do the tweaks than for us to exchange 6 gazillion emails.

So WTF do I want? Good question. I seem to whine about doing figures, yet also enjoy doing them.

Doing science and getting data is hard. Writing papers and making figures is necessary, but it is also much easier than doing science and and is super fun (for me, at least), and I don’t know why junior folks don’t savor it. Savor it, damnit!

What I want is for my trainees to take pride in their work and to be hungry to publish their work. I want them to chase me and nag me to finish the paper and to send me 15 versions of each figure and to be engaged in writing their work up for publication. I don’t expect them to do anything perfectly, but wish they would want to do things, on their own, without prodding. I know being effective at presenting takes time and practice, but I don’t think you can learn to have a fire in the belly.  Apparently, what I need are students with chronic indigestion…


One of the things that annoy me most about collaborating are collaborators who operate on the timescales much different from mine, usually because our priorities aren’t well aligned. I have already written about this particular issue before, but as it periodically resurfaces, I periodically get re-irritated and thus have to periodically re-vent, and reposting old rants just doesn’t seem to have the same therapeutic effect.

I have a  collaborator who doesn’t seem to be encumbered by urgency when it comes to paper submissions. In the past, after a disastrous few papers, where we drove the co-advised (and since graduated) student crazy, I came up with a strategy: the student and I work on each paper until it’s done and ready for submission, I schedule a time with the collaborator in advance for them to look at the essentially polished paper, they suggest touch-ups (which they expect accommodated), I enter those and we submit. Sure, the student and I do all the heavy lifting, but at least the papers get written and edited fast.

This week I have been driven crazy again, and I can tell you it’s a remarkable feat of self-restraint that I didn’t already write about all this days ago.
Early this week, I  emailed the collaborator to tell them that I would be done with the paper later in the week, and then would be off to a conference starting next week, and I asked it they could perhaps look at the paper during my absence. The collaborator wrote back to tell me that they too were leaving town,  but not until around the time when I was to return from my trip. The problem is that they decided they had absolutely no time to look at the paper in the time preceding their departure  (which was almost three weeks from the point at which we were emailing and nearly two weeks after the point at which the final paper was eventually sent to them), but said they they would look at it soon after they came back.

I am really pissed, because, as far as the current student and I are concerned, the paper can be submitted today. It is not a rough draft that requires massive edits, I already took care of all of that. Still, the colleague supposedly does not have the time to look at it in next two weeks, they supposedly have weeks of their time in town fully obligated in the middle of summer (no, they are not writing a proposal), so we now have to wait additional 3+ weeks from the point of completion for the colleague to put on the trivial finishing touches.

This happens every time, with every paper. I do not buy that the colleague is busier than I am, because I am pretty darn busy and their group is not bigger than mine. These joint papers are simply not a priority for the colleague, which is OK, but they *are* a priority for me and the student, and if they cannot help they should at least not hinder!

If submitting a paper were equal to having sex, then the colleague would now be cock-blocking me. I think it’s safe to call the colleague a pub-blocker.

I have been in situations where I was the middle author, cared little and didn’t have the time to go through the paper in detail; in such cases, I either took myself off the paper or found the time to at least quickly skim the paper and said it’s OK to go as is. You either care and find the time to look at the manuscript, or you don’t care and consequently don’t find the time, but then at least you trust your collaborator that they can submit a coherent manuscript. The worst scenario is that you don’t care and don’t find the time, but also want to hold the reigns on submission. That is really, really douchey controlling behavior.

No, I don’t want to wait three weeks or more to submit what is essentially a finished paper. As a courtesy, you have two weeks. The last three days of those two weeks you are away, well boo hoo. There are the other 11 that you are here, find the freakin’ time.

Here’s the deal: papers are important. Papers are VERY important. Papers and graduated students are our products. There is possibly no aspect of our job (our job = professor in a STEM field at a major research university) that is more important than getting papers out. Published papers enable everything else: students graduating and getting jobs, new grants being funded, knowledge advancing.

I have no idea what the collaborator has in the pipeline for nearly two weeks prior to their departure that would prevent them from sitting to read the paper for an hour or two. But whatever it is, unless it’s editing of a whole $hitload of their other papers (and I know for sure that it isn’t) , IT’S NOT AS IMPORTANT!!! Stop pub-blocking. Move stuff around, read the goddamn paper, so we can send it to review ASAP. Then you can get back to whatever leadership or other service BS is so pressing in the middle of the summer. And you are very welcome.


I haven’t been blogging much as I am a) recovering from the semester and b) writing technical stuff 24/7. So I am a little tapped out. As I am thinking about writing, it’s fitting that I write about writing.  Perhaps I should go full-meta and write about writing about writing…  For now, I give you a few technical writing and publishing vignettes.

The wimpy paper

The paper is competently written, correct, and boring as hell. Why? Because there is no story. Each figure is clear, pretty even.  The problem? The text pertinent to each figure is banal — just stating what the figure shows, what each symbol or line means (needlessly duplicating the caption), and trivially reading off trends. For example, all you get is

” For parameter C>C0, A increases slowly with increasing B. For C≤C0, A is independent of B.”

Yeah, I can see that from the figure, so what? Tell me why it’s important! What does it mean about the system at hand? Give me some nontrivial insight that the figure corroborates. For instance, “This dependence has been predicted based on the Orthodox Theory, but it was never experimentally measured before. The measurements presented in Fig. X confirms that Orthodox Theory accurately describes the underlying physics.” Alternatively, “The dependence of A on B presented in Fig. X is in contrast with the Orthodox Theory, which predicts A to be a monotonically decreasing function of B for all values of C.” Then go on to say what you think happens and why, ideally support with a different set of experiments or new theory theory.

I hate the wimpy, non-committal papers where the authors don’t state any conclusions or make any strong statements. Science isn’t stamp collecting, it requires you to understand and interpret data; the understanding and interpretation are what’s included in the body of knowledge.

The “I will make you sweat” paper

In my field (and many others, I am sure), there are comprehensive papers and there are letter papers that are typically 4 pages long. A well-written letter should be readable and understandable with <50% of the focus on the part of the reader. You should nudge me towards what I should think, with figures and text playing off and reinforcing one another. Don’t make me sweat like a constipated buffalo, reading two terse, cryptic paragraphs over and over again, trying to figure out what on earth you are talking about and how any of it has anything to do with the data in the figure (or common sense, for that matter).


This is mainly for professors, but others can play as well, and I know the variation will be drastic among fields.

How many papers can you conceivably write in a year?

I mean, the papers on which you are the lead author or do a significant amount of writing? I work almost exclusively with trainees and each paper is a lot of work: I can’t just sit and write it, we have to do the back-and-forths, the edits and the teaching. It takes a lot of time. I think my upper limit for papers where I am really involved would be 1 paper per month on average (more during the summer, less during academic year); usually, it’s less than that, roughly 1 paper per group member per year (senior ones can do 2, junior ones have 0, but it comes out roughly about 1 per group member per year). Full disclosure, I had 8 papers last year; I suppose if I had more than 12 people in the group we’d run into my own bandwidth limitation.

I see these people with 20+ papers per year from their group and I wonder — how? I suppose it depends on the length of the paper (a 4-page letter versus a 12-page comprehensive paper), how many senior people are on the paper (which can be a blessing, as they hopefully know what they are doing, and a curse, since they can be super busy and make it hard to get the edits done with), if you have good postdocs or research scientists… But still, how do you produce so many papers per unit time? I suppose there are these elevated planes of productivity that are like Mount Olympus: only a select few ever reach them.

Which brings me to a related question: There is definitely a need to edit and revise papers before submission. At some point, the gains from successive edits become insufficient to justify the extra time. This issue is particularly important when attempting to publish in high-profile journals,  as an insane amount of polishing goes on just to get a chance to pass the editorial desk and go out to review. A recent paper of mine with collaborators took years of hard work of several people, and about 2 years of writing and editing, and eventually went into a Glam Offshoot. Unfortunately, it seems we may have missed the wave of interest or whatever, because, after all that time and effort and the battles with reviewers, it doesn’t seem to be attracting much attention. Oh well.

So how do you decide when to pull the trigger? When it’s perfect? (Never.) When you are sick of it? When the student reaches the point of sending you two emails per day, begging you to submit already? When your grants are up for renewal? When you’ve done the three back-and-forths with student, edited the final version for two weeks and it’s as good as it’s going to get in the near future?

Update: This week’s PhD comic

Writing Papers with Graduate Students Who Don’t Want to Write Papers, Take Seven Gajillion

Over the past few weeks I have been working on papers with several students in parallel, and I am again pulling my hair out and wondering if there is a  way to get the writing done and the students trained without me going bald.

Reporting findings in written form is an inherent part of doing science. If you don’t publish your work, it’s as good as nonexistent. But, even more generally, scientists and engineers with advanced degrees will likely have to write technical texts one way or another, regardless of where they work, so it is important to train graduate students to write.

To me, writing has always been the easy, enjoyable part of every project. Sure, literature survey for the introduction is a bit of a pain the butt, but starting to write a paper means that the technical hurdles have (mostly) been overcome, that we have done the hard stuff and now it’s time for the frosting on the cake. Getting to write the paper has always been the reward part for me. Also, writing helps me distill my thoughts: the process of trying to explain what was done and how the reasoning went in a coherent, fluid form, often helps me understand the problem even better than before.

In contrast, I find that most of my students dislike writing. While for international students it may be the insecurity about their command of English, I find that even native speakers and non-natives with excellent command of English would largely still rather not write than write. Even students who may be very good and engaging presenters are often surprisingly lackluster writers or just horrible procrastinators when the time comes to start putting words on paper. “That’s because they are novice writers,” you say, “surely they will learn with practice, and writing will become easier;” that’s true, but only to a degree. Many simply really, really don’t want to write, don’t want to learn how to write, and would rather I left them to do their reading, derivations, and coding. They love being immersed in the technical nitty-gritty of their projects.

Writing is to science what eating fiber is to diet: necessary to keep things moving.

When you were little your mother probably bugged you about getting fiber through fruits, vegetables, and grains. Once you are all grown up, you probably understand the importance and include it in your diet, even if you don’t really like eating it. With my PhD students, I definitely stress very strongly the importance of technical writing. I used to iterate ad nauseam with each student until each paper was perfect; that took forever and the process often didn’t converge, so I had to take over. Right now, after the framework of the paper is agreed upon, I have a policy of 3 back-and-forths with edits before I take over and do the final rewrites; I ask the student if he or she wants to iterate more, as occasionally I do have a student who does want to keep going a little more to perfect their craft. However, most students are very happy when I take over; some procrastinate endlessly with their edits, some will tell me that they hate writing and don’t want to do it, or that it’s just really hard and they would rather I did it.

You know, it’s my duty to emphasize the importance of technical writing to students and to offer them the opportunity to learn. But do I actually have to shove the writing down their throats? I mean, if they are resisting learning, is it really my duty to force them to learn to write? We are dealing with young adults, but adults nonetheless.

I am wondering if I should reduce the mininum technical writing requirements to “full drafts for those who want to learn how to write, figure and figure captions for those who decide they don’t care to learn how to write,” or some similar scenario. Basically, when I see someone is fighting me and just does not want to write, perhaps it is OK for me to say “Fine. You supply the figures I tell you to make, I will write the paper. But don’t tell me that I didn’t tell you it’s important to learn how to write, and if you ever want to have another crack at it, let me know. In the meantime, you are relieved of this ominous duty.”

What say you, blogosphere? Is it OK to relieve the suffering of both myself and the students who really really don’t want to write?  Sure, that will leave them scientifically constipated, but I’m tired of having to chase them in order to force-feed them professional whole grains. I am not sure it’s in my job description or in anyone’s best interest.

Professorial Hypertension

In STEM fields, a graduate student works on supervised research and is part of a research group led by a professor. Learning how to write up technical papers for publication is one of the most important parts of PhD training, so the student will typically be tasked with producing the first draft of a manuscript, which then gets heavily edited by others involved in the work, most of all the professor. This practice, however, is not without danger


A Plea

Dear colleague:

Once you are a grown-ass scientist with several years of experience past your PhD — which means that among other things you are not a graduate student of mine, for whose technical writing practices I am responsible and after whom I (grudgingly) accept that it is my job to clean up prior to manuscript submission lest we all be embarrassed — then pretty please with a cherry on top: 

— Don’t send me a manuscript draft in a state where it’s impossible to comprehend what a figure actually represents. What is the quantity you are plotting, for which system/sample?

— Be cognizant that someone is supposed to at least approximately be able to read stuff off your graphs, which means that a total of three ticks with numbers (with no ticks or numbers in between) on the whole goddamn axis is simply not enough.

— Read the goddamn draft before you send it to me. Go over it as you would when you review other people’s papers; notice that there are multiple places where you make pretty strong claims of “common knowledge” that’s not really common and where you don’t actually provide a citation. It pisses me off when there are 10-15 places where I felt a citation was really necessary but it’s missing.

— Read the goddamn draft before you send it to me. Pretty please decide on  the notation and don’t change it 5 times throughout the paper (because you cut and pasted from 5 different papers) and clean up the equations.  It’s not really all that hard. Really.

— Read the goddamn draft before you send it to me. You have to read it in order to realize that, in the part that you wrote, the flow is terrible. It is hypertension-inducing even in the under-caffeinated among us, and in my case a vein might pop. Edit the draft, for goodness sake, I know you can. You are not my student, I should not have to clean up so much after you. More importantly, I don’t want to. You are a grown-ass scientist.