In grad school you do a lot of technical writing. You write research summaries for your professors, guides for your fellow students, outlines for courses you’re TAing, and (if you’re lucky) you even get to write journal papers. You might assume from this that grad schools require English classes or writing classes. They do not (at least mine didn’t). In my experience, grad students learn to write by writing a lot and being judged on it.
Most of what I’ve written never gets more than a few comments or questions on the topic, but when I write journal or conference submissions, I tend to get a lot more structured feedback. Since the good feedback on my own writing has been fairly rare, the most helpful thing that I’ve done to learn how to write better is critique other people’s work. Critiquing other people’s work allows me to hone some writing skills without the emotional pushback of being invested in the content that’s already there. It works even better if I’m currently writing a paper while I’m editing someone else’s, because I can immediately apply what I learn from editing to the paper I’m writing.
As I’ve progressed as a writer, I’ve noticed that grammar and sentence structure are really only the first step to writing well. Once you memorize the rules, it’s pretty easy to throw together a sentence that doesn’t make someone cringe. The hard part comes when you try to use those sentences to convey complex ideas. What part of the idea do you want to present first? What if the audience doesn’t know the background material? How do you make the paper interesting? What do you do if nobody understands the thing you’ve written, or if they don’t catch the most important part of it?
What I’ve come to realize is that the answers to all of these questions revolve around two things: ordering concepts and choosing detail level.
Ordering Concepts
When you’re writing a technical paper, there’s a lot of different things to cover. The naive approach, which I’ve seen used a lot and which I’ve even used a time or two, is to present concepts in the order that you figured them out. For example, if you’ve designed a piece of hardware to solve the problem, you might write the document by going through all of the design decisions that went into it: going over what it has to do, the electronics design, the mechanical design, implementation, testing, the second prototype, re-testing, etc. This works alright, but it often isn’t the best way to go.
It can be much better to organize concepts by complexity instead of chronologically. This is especially true for documents that don’t detail a specific design or discovery. In this case, you want to start with the most simple concepts, and then present ideas that build on those. This kind of document leads the reader from simple to complex, rather than from start to finish. If you’re writing a report on the effects of opium use on Chinese culture, then you might want to start with the individual effects of opium, then progress to interpersonal effects, large scale social and economic impact, and then the whole historical picture.
There are many more ways to organize a paper than just these two, but these are the ones I’ve had the most success with. The main thing you want to do is have some kind of organization at all. Don’t start writing without knowing what the overall organization of the paper is. It can be annoying to have to sit down and think things out when you really want to get started writing, but its’ worth it. For a document you might spend a week or more on (or a month or more), spending some time up front on figuring out the organization structure can save you lots of time in the end.
Choosing Detail Level
I’ve read some incredibly boring papers about subjects that I loved. The main thing that all of these papers had in common was that they used the same level of detail throughout the paper. New writers are often more comfortable at a single level of detail, so their paper either reads like a list of facts (if they’re very detail oriented) or feels like it has no substance (if they’re always high level). When it comes to technical writing, I’ve noticed a lot more of the former.
No matter who’s reading your paper or why, you have to get them to care about the content if you want them to remember it. Often they’ll do this themselves if you can show them why the content is relevant. When encountering new information, people need some way to connect it to things they already know in order to retain it. This is why lists of facts are so hard to read, there’s no high level context. The high level context before lots of facts and theory will prime the reader with similar things they’ve heard before. This allows them to associate what they’re reading with what they already know, and it makes the document more interesting.
On the other hand, if all you give is high level context, then the reader won’t learn anything from your paper. At that point, there’s no reason for them to even read it. You need the lower level detailed explanation. With technical writing, this usually isn’t the hard part. As a grad student, this was always what I started with when I had to describe a study and the results.
It’s clear you need both high level context and low level detail to make your paper worth reading. The main question is what ratio to use and how to organize the high and low level sections.
My own opinion is that each large concept needs some high level to tie it to things the reader already knows before the low level explaining the concept itself. When figuring out how to arrange these, I usually fall back on that old teaching advice “first tell them what you’ll tell them, tell them, then tell them what you told them”.
Whenever I have a new concept to cover (in the right place according to my outline of course) I introduce it with some text about why it’s important. Then I go over the concept. Then I talk about what the concept means and what it implies about other things in my paper. Often, this serves as a good introduction to the next concept I want to write about. This is pretty similar to the topic sentence/detail sentence/transition that they taught me in elementary school, just on a larger scale.
Putting it all together
I’ve found that using these two concepts not only makes my writing better, it makes my writing faster. Once I have an outline using whatever structure I think is best for the paper, I can go in and add some context in each section talking about why the different sections are important. That’s easy to write, because I just write down why I put the sections there in the first place. Then I can put in the details of each point.
The whole thing is an iterative process, so I usually end up with a different outline or structure than the one I started with. The act of adding in context and details in different places reminds me of other things I need to cover so that it all makes sense. After that, it’s just a matter of editing it 40 or 50 times before I can send it in.