technical writing

Type-type-typitty-type

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

Prolific

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…

Comic8_Hypertension

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.

Sincerely,

Xykademiqz

Doing Science, Advising Students, and a Bit of Shockley

There is a small programming assignment I like to give my beginning grad students or upper-level undergrads who want to do research in my group. The assignment is a reasonably simple but quite accurate simulation of a system they all encountered during undergraduate studies. Most students never really ask themselves what the approximations are that result in the textbook results. The simulation, which is perhaps several hundred lines of code, solves several coupled partial differential equations in one spatial dimension; the students learn about the numerics  as well as about the theory that describes the behavior of the physical system beyond the textbook approximations.

I have a new undergrad who is great, smart and motivated, and who fit in the group very well. If I am lucky, he will stay here to get his masters and then will likely go someplace with better brand-name recognition to do a PhD; I understand that’s what the student must do as it’s the reasonable thing to do, but at baseline it’s always somewhat infuriating. When some colleagues at Über Unis look down on us from State Schools, I wonder if they ever realize that those awesome kids with research experience who get into their labs did not sprout from the ground, somebody who knows how to do science has actually trained them. The best American students in the physical sciences have plenty of options to go to the most prestigious universities and, if they are well advised (by whom, I wonder?) to realize what’s out there for them to apply for, they can do it on prestigious fellowships. Luckily for me, there are plenty of very smart international graduate students with whom I get to work, in part because options are more limited for them for a number of reasons. But that’s a topic for another post…

The undergrad did a great job, was able to write the code and the code performs the required checks accurately. Then I said “Great! Now you can use it to teach us something new about the model system.” The student was puzzled, we talked a bit, he came back a week later with what he felt were pretty boring results, not knowing whether there would be anything interesting in such a simple system. I said “These are all the things off the top of my head that you could inquire — how realistic are all the textbook approximations, to what extent they hold up in a more realistic simulation, how important are a these different details in the simulation for the physics, what happens if you completely disregard this or that and how it would translate to reality…” You get the point. He thought there was nothing there and to me there were 15 interesting things to ask. I gave him my little speech about how code is like a piece of experimental equipment — once you are done lovingly building it, the science part is deciding what questions are both worth asking and are possible to answer with the tool that you have. 

Left to right: Bardeen, Shockley, and Brattain won the 1956 Nobel Prize in physics for inventing the transistor. Bardeen went on to win another Nobel Prize for superconductivity, and is considered one of the nicest and most unassuming scientists in history. Shockley was said to have had “reverse charisma” — when he entered the room, you’d instantly dislike him.

This exchange reminded me of this very nice blog post on Dynamic Ecology, in which Brian McGill discussed the pretty famous paper by William Shockley, a Nobel Prize winner (with Bardeen and Brattain) for the transistor and thought by many to be one of most brilliant and most nasty people they had ever met.  Shockley had been able to identify and recruit smart people for Shockley Semiconductor Labs, whom he then drove away (the Traitorous Eight) into Fairchild Semiconductor, a company that became the incubator for the Silicon Valley,  having spun off a number of companies, “Fairchildren”, such as Intel and AMD. Anyway, Shockley’s paper is worth reading for a number of reasons; it is actually pretty famous for its discussion of the log-normal distribution of productivity over professional scientists. What Dynamic Ecology pulled forward and what I find interesting here is Shockley’s hypothesis that productivity depends on the ability to clear multiple hurdles, and he names 8. Being good at all of them is key, you cannot be exceptional at one thing and inadequate at another, as success depends on the product of functions that measure one’s: 

  1. ability to think of a good problem
  2. ability to work on it
  3. ability to recognize a worthwhile result
  4. ability to make a decision as to when to stop and write up the results
  5. ability to write adequately
  6. ability to profit constructively from criticism
  7. determination to submit the paper to a journal
  8. persistence in making changes (if necessary as a result of journal action).

Everything here depends in part on talent, personality/temperament, and training (much of the latter by osmosis).

For instance, there are many students who have #2, i.e. they are smart enough to work on a good problem, provided that someone else formulates it (#1). It takes talent as well as experience to learn what constitutes a good problem, the right combination of interesting and doable in a reasonable time and with available resources. Similarly, with #3 and #4 — it takes experience to know when something has become a publishable nugget, when the data is enough to support a compelling and convincing insight. Once you realize that #5 and #7 are important (and they really, really are: all the nice work you might have done is as good as nonexistent until you publish it), you need to have a good PhD or postdoc advisor from whom you can learn how to write well. If you are a talented person, you can become really good at many of these aspects early in your career with good focused training. Otherwise, it can take you much longer to realize the importance and then teach yourself the skills, and your early career can be impeded.

#6 and #8 essentially mean grit and they are extremely important; probably even more important for grants than papers these days. Most of my grad students get discouraged when we get revise and resubmit with potentially lengthy revisions, because they feel we had already submitted a great product so why this silliness now. And they may or may not have a point, but the key is to go on.  I have had to do it many times already, and I am simply desensitized to it. We have to do it so we do it. But I see that students can wonder whether all the effort is worth it — at the end the result is a paper. You gotta love getting papers published. And having a thick skin does not hurt.

Anyway, this post was written in fits and starts, so I think I totally lost my train of thought and with it my point. But it’s fun to think about what success entails and exciting to see a young person starting to learn about the moving parts of the enterprise of science — what it means to formulate a problem, execute a project, and finally disseminate new knowledge. I guess my point is that I really love advising students.

Proposal Review Silliness

Lately, I have been reviewing proposals and playing a game with myself  called “Guess how many grants the PI already has based solely on flipping through the proposal to see the formatting.” The correlation is quite pronounced: people who have a reader-friendly layout are universally better funded than those who don’t. When you start reading, you also see that their text flows better (even if the ideas are not necessarily earth-shattering and they end up not funded). Successful grant writers definitely take care of readability, and readability includes thinking about the layout.  Good, reader-friendly layout helps your reviewer think happy thoughts and not dread reading on, as opposed to start hating you with a passion 2 pages in because the gray walls of text gave him/her a claustrophobia attack.

These tips have been mentioned online many times, I am sure, but they never get old: for goodness’ sake, put some space between paragraphs,  go with spacing that’s greater than single (1.1 to 1.2), and break up the text. Ideally, each page will have a figure, a table, or at the very least one or two displayed (as opposed to inline) equations. Look at these three samples — the text from my earlier post, “Musings on Networking” — which format seems the least stifling and the most inviting?

MusPDF1_Page_1

Version 1: single spacing, no break between paragraphs

MusPDF2_Page_1

Version 2: 1.1 spacing, 6 pt break between paragraphs.

MusPDF4_Page_1

Version 3: 1.1 spacing, 6 pt break between paragraphs, plus a figure

All the text is in 11 pt Times New Roman. I am a Times New Roman fan, it’s a classic font and you will never go wrong with it. There are people who like sans serif fonts like Helvetica or Arial, which are just not my cup of tea. But if a funding agency says a font is fine, then it’s fine; have fun with it. Also, I know people will say “But I am constrained to 15 (or however many) pages, I can’t waste space on silly tricks.” Yes, you can and you should. You can purge the fluff and become even more clear and succinct than before, and the reviewer will be happier for it in more ways than one.

— Do give your proposal a title that is short and catchy, but please also be accurate. I got several proposals roughly entitled “Pie in the Sky Is High But I Can Fly” and then one is about the aeronautical engineering of taking off, another is about optimizing sugar-to-flour ratio in pie recipes, and the third is about why the sky is blue and if we can manipulate its color. 

—   There are always fads, hot areas. Once a topic is established as hot, money gets thrown at it, and many people move into the field. However, big groups move faster, and if there are low-hanging fruits, they will be picked by the most nimble. If you are a junior faculty who is just starting with 2 students, you will not be beating a big-named guy who has invented the field, has multimillion-dollar centers funding him to do the work already, and has an army of minions going after the easy pickings. At best, you’ll be just another “me too.” At worst, you will never get any money to do what you are proposing, because groups much bigger and much farther along than you proposed and got funded to do that same exact thing last year and the year before.

When you are just starting up, be mindful of what your strengths are and how fast you can conceivably do something. If you are phenomenally successful at getting money and able to grow much faster than an average new prof, then sure, go ahead, toe to toe with the big guys. But if you are not, then you need to find a niche, something you can do better than others, because of your expertise or how you approach the problems or because no one figured out that some specific aspect may be both important and doable, something that is uniquely yours, not just an obvious question within the latest flavor-of-the-week topic. Be realistic about what you can pull off with the money and personnel you have. And when you identify your niche, then jump on it with all you’ve got.

—  I laughed out loud in my office at a sentence that said something like “In year n of the project, the results will be published in a journal of impact factor at least 10.”

AHAHAHAHAHA! Only 10? Why so low? The stuff is guaranteed to get into Nature! Seriously, people. That’s just amateurish. I can forgive when a graduate student lists 10 papers “in preparation” or “to be submitted to Nature Progeny” on their CV, but a grownup scientist should know better. You can tell me you expect high-impact stuff, but better yet write your proposal in such a compelling fashion that it is crystal clear to me this will be high-impact stuff, in which case I will strongly advocate for funding you. In contrast, the silly silliness of “We’ll totally publish in a Super Duper Glam Mag” is just silly.

This Bean-Devouring Leprechaun

Over the past few days, I have reviewed a small mountain of student conference abstracts, as the deadlines for two conferences where we usually have a strong showing are approaching. This exercise has reminded me of some of my favorite technical writing slips.

— Don’t start a sentence with an abbreviation, i.e., don’t write “Eq. (3) can be simplified…” or “Fig. 5 shows the dependence…”  At the beginning of a sentence, always write out the full word instead, i.e., “Equation (3) can be simplified…” or “Figure 5 shows the dependence…”  Abbreviations are fine elsewhere.

— Compound adjectives need hyphens. For instance, is should be “a well-deserved honor” as opposed to “a well deserved honor.” However, “the honor was well deserved.” In both cases, “well” qualifes “deserved”, but in the first example both “well” and “deserved” together form a compound adjective that further qualifies “honor.”

— If hyphens start making you dizzy, such as in “the 5-nm-wide ribbon,” consider rephrasing, such as “the width of the ribbon is 5 nm”

— Commas are your friend. Commas make the world a better place. Love them, use them. 

— Don’t use “this” or “that” as subject in technical writing (it’s OK if writing casually), i.e.,  don’t write “We report that the leprechaun fart rate increases cubically with their bean consumption rate. This implies that leprechauns should be kept on a bean-light diet.” What does “this” refer to? The fascinating bean-fart relationship? One of the many nouns in the previous sentence? Something like “This dependence implies…”  would work. Maybe I should start adding “bean-devouring leprechaun” after “this” or “that” every time I catch this type of mistake.

A pot of gold… or a pot of beans?

—  Statements should be kept emotion-neutral, especially if they refer to the work of others. For instance, you can say that your approach is more accurate or has a wider range of applicability than the approach of Schmoe et at. , but don’t say things like “Our approach is vastly superior to that of Schmoe et al. because they only relied on this lowly old-fashioned approximation. ” Also, while it is wonderful that you are excited about your research, you can’t say things such as “Amazingly, we found that Schmoe et al. had it all wrong.”

— Don’t say “To the best of our knowledge, this has never been done before.” It’s just silly — it’s your duty to do the most comprehensive literature survey that you possibly can and then stand behind what you consider to be the state of the art. “To the best of our knowledge” implies to me that you might have slacked on lit review and are preemptively apologizing in case you missed something and the referee gets upset.

— Always write with an audience in mind. The readers are not inside your head; they don’t think about this problem of yours all the time like you do. What you think are the most fascinating aspects of your work may not, in fact, be the most important ones to emphasize, either broadly or to a specific audience. Leading with the motivation and insights that your audience will connect with is key to creating enthusiasm about your work.