Technical writing: How to write gooder

Know your audience, it’s the first rule of technical writing. I’ve taken several technical writing courses during my education and they all start off the same way. KNOW YOUR AUDIENCE! In my experience that is usually the end of the advice given. Most technical writing courses assume you know how to write, an odd assumption when you’re supposed to know your audience. Today I’m going to go over what I do BEFORE I write, in the hopes that it will help some of you. Fair warning, this is long and detailed!

I am not a expert at technical writing. I’m barely a writer. However, I get feedback all the time from reviewers that my papers are well written. That may not be the case for my blog in general, I rarely edit my words here and my blog posts are more a stream of consciousness than a polished and carefully worded thought. That’s because I don’t have the time to dedicate to editing and rewording my blog posts. It’s a feature, not a bug.

Technical writing takes time. A lot of time. As I mentioned yesterday, a general rule you can live by is simple, your first draft is, and will always be, garbage. That doesn’t mean you can’t improve on it and that doesn’t mean you shouldn’t have a strong foundation. Garbage in means garbage out. If you do the work upfront you’ll save yourself work on the backend. Trust me, I’ve seen it firsthand and it can get messy when you realize what you said, and what you wanted to say, are two different things!

Now a quick disclaimer as we go into my writing methodology. This is very user specific, which is to say what works for me may not work for you. The reason this post exists is because I’ve seen other writing on how to read technical papers, but very little on how to actually get setup to write them. It’s my hope that by showing you my process you can augment it to suit your needs or come up with a whole new way that makes sense for you. Now, this is going to be long enough as it is, so no more disclaimers, let’s get started.

What does a work of fiction and technical writing have in common? You’re telling a story to an audience who has generally not been introduced to your topic. Technical writing often is done because you’re bringing something new into the world, a technique, an interesting finding, etc. Both fiction and technical writing require you to be able to tell a good and coherent story. The question then becomes how do we do that?

I like to start by creating a bulleted list. It’s an overview that I will use to create my story. If you’re familiar with animation or film making think of this like a storyboard. Mine starts off simple I use a blank paper/word document and at the top I put my starting point and the bottom I put the end point.

Pro-Tip: Sometimes a starting point is hard to define, but have no fear! If your having trouble filling that out, skip it and jump to the end of the page. Here you can add your end point. What did you do that was new? This should be a much easier question to answer. Once you’ve done that go back and think about the starting point. What lead you to the end point you just filled out? Something triggered the discussion that lead you to that even if it was just your PI giving you the topic of research. A well defined starting point and end point will go a long way towards creating a clear story.

So now you have something that looks like this:

• Starting point
• Ending point

Just a quick reminder, you should have plenty of space between the two if you’re working on old fashioned paper. If you’re doing this in word or some other program, you can adjust it as you fill in.

Now the semi-difficult part. We fill in the middle stuff. Don’t worry, this isn’t one of those how-to guides that will leave you scratching your head on how to accomplish that. I’ll walk you through how I do this. First, we need to think of the major milestones or steps we hit. Think of these as the main points in our journey from start to finish. If I travelled all around the world, these points would be the places I was most excited to see or that give the most interesting details to the story. We don’t need to hear how you slept on the flight, but if the plane (your project) had problems, this would be a good thing to highlight… or maybe not, but we’ll dive into that in a minute.

Continuing with our travel example metaphor we can further narrow down our “points of interest” to important things that we did to get there. Maybe a issue with your project would be interesting to cover, but didn’t impact the final result so we can toss it out of the timeline and focus on a clear and narrow path from point A (start) to point Z (end). Each of those points should help propel us to the next point and nothing is set in stone so add anything you think is important and we can scratch it off as we refine our story.

At no time should any of this be set in stone either. If you find the path you highlighted is lacking you can go back and revise it or remove sections. This is just a guide, like a map you’re making. Like any map, you may later find a better route. It’s okay to go that route instead. So now you should find that your bullet points should look something like this, which I filled in using my travel around the world analogy and some themes from my field of research:

• Starting point – What’s the need?
• Got my passport, determined what was needed to fill the “gap” (fix a need)
• Landed at west coast of the U.S. needed to decide which country to hit first, determined my methodology.
• Landed in Japan, had to refuel, listed equipment needed for experiment
• Thailand is amazing, did some cool experiment that I could only do here.
• Russia was close by compared to the journey home so we went here – dead-end
• In Germany I found some new/interesting result from the experiment
• Landed in east coast of US – How does this experimental result help fill the “gap” (fix the need), discussion of future work, limitations, etc
• Ending point – the recap… maybe?

I sort of quasi- filled in the timeline as best as I could with the broadest information possible. (Notice I crossed out a failure here) At this point I’m not sure if that helped or made things more confusing. Here’s the main idea, you need to get from point A (Start) to point Z (end) in the most direct way. If you had 99 failures and 1 success, you can discard the 99 failures to share the one path you got to success.

Side note: This is unfortunate, because the 99 failures may tell us much more than the 1 success, but we don’t have a journal for null results. We really should and that’s a topic for another time. However, we don’t so we’re left talking about the single success we had and the formula used to reach that success.

Okay, so we’re done and can start writing now… right? Nope. What I like to do now is segment those sections and create subsections so that I can make notes of things that should be highlighted in those sections. Let’s take a quick shot at what this looks like:

• Starting point – What’s the need?
  • Statistics, history, etc.
  • Maybe how much money is spent on this because we don’t know how to fix it better/ have better science.
  • State of the art, here we would look at other papers talking about our starting point.
• Got my passport, determined what was needed to fill the “gap” (fix a need)
  • This is the problem our end goal will fix, how?
  • This leads into methods, so we can highlight some of the things we will use to reach the end goal. (using our travel metaphor, planes, trains, and automobiles).
• Landed at west coast of the U.S. needed to decide which country to hit first, determined my methodology.
  • How many subjects/whatever do you plan on using?
  • What is the process you used to create this new thing
  • What techniques did you use/ how did you modify them
    • Remember this isn’t a place for the results, this is a place for how you got those results!
• Landed in Japan, had to refuel, gathered equipment needed for experiment
  • Here we’re still in the methods section so we can cut this out in favor of just combining the information we would put here. The only reason to create a subsection is if we have something that needs its own subsection. Since this is an example let’s cut it here.
• Thailand is amazing, did some cool experiment that I could only do here.
  • This is part of our results section believe it or not. We talk about the result from the experiment, but not the things we conclude from it.
  • Figures are usually a good thing, so are tables
  • Include the interesting results you found from the experiment, but we don’t discuss those results here, that’s the next section.
• In Germany I found some new/interesting result from the experiment
  • The discussion section, where we talk about how the results from the experiment show that we’ve found something new/interesting/unique/novel and how that will help others
  • Here’s an interesting result that we didn’t expect to find, highlight me…
• Landed in east coast of US – How does this experimental result help fill the “gap” (fix the need)
  • Still part of the discussion section, maybe we should combine this unless we want to have a subsection talking about this specific result and how it impacts our “gap”
  • Does it need a subsection? Maybe if it’s something we really want to highlight.
  • Even the best experiments have limitations, here’s where we talk about them
  • Future work is important. Now that you filled the “gap” what else can you do with this information that you couldn’t before?
  • Is there some part of the experiment you would do differently next time? This is where we highlight it.

• Ending point – the recap… maybe?
  • Recap the interesting findings of the work you did and why they are important, this shouldn’t be long and sometimes i isn’t even included!

Okay so I filled it in using some of the conventions I use in my field. Since you may be in a totally different field I’ll cover what we use in engineering I’ve worked in the mechanical, biomedical, and neuroengineering fields and they use roughly the same format. We typically have a:

Introduction, where we talk about the “gap” in science, why that’s a problem, who it will effect, and why we want to fix it. In my field, we use a lot of statistics to drive our point home, the US spends $XXX,XXX on this neurodegenerative disease with no improvement, things like that. We can also give a brief overview of how we will solve this, but the detailed stuff goes in the methods.

Methods section, where we go into details about the experiment we did and how we do it. We cover all the needed math/neuroscience/etc. that the reader would need to know. A good methods section is one that a reader could follow themselves to do the experiment without your help. Think of it as a recipe, make sure you are clear and thorough. This is where others reading your manuscript helps because something that is very clear to you may be shockingly unclear to someone else, it happens to me all the time. You get too close to the research and know the topic so well you forget others do not.

Results section, here we talk about the results from the experiment. You’ll want to talk about the cool stuff that you found, but this is not the place for it, at least not in my field. We save that for the discussion. In the results we give the data we collected from our experiment in a concise way, graphs, tables, figures, etc are not uncommon in this section and it would be surprising if they weren’t here (at least in my field).

Discussion section, this is (finally) where you get to talk about how cool your results are and why others should be super excited by them! You can use the combination of previous work (by others and/or yourself) and the work you just did to attempt to fill some sort of “gap” in our knowledge. Here is where you explain how your result solves the $XXX,XXX spent each year on a neurodegenerative disease without a result. We also go into experimental limitations and future work here.

Conclusions section, sometimes in my field this is combine with the discussion section. Conclusions are often times a cliff notes version of the discussion. They are typically just a few sentences long and highlight what you found that was new and interesting and why the work is important. This is a flexible section and it really depends on your field and journal/conference you’re submitting to.

Well this is super long, but there is one other thing that we should discuss. Order of writing! Let’s just get this out of the way now, you don’t need to write in order. I know, we all have that overwhelming urge to write it start to finish. However, like that feeling that you need to have your feet under the covers when you sleep, it’s not real. You can write it in any order you want!

I typically like to fill out my Methods section first, then the results. I’ll do the introduction and the abstract last (which I didn’t cover because it’s just a recap of the start to finish of your story in ~250 words or less usually). The results you can’t do until you have results so order of operations for me is write the methods, do the experiment, then rewrite the methods (if needed) and fill in the results. I like doing the introduction last because it needs the most time and I want to be able to give it my full attention when I do it without worrying about the rest of the paper. Once that’s done the abstract practically writes itself and you can pick key sentences from each section to create the rough abstract, then refine as needed.

So there it is, the method I like to use before I start writing my papers. Like I said it may or may not be best for you, and that’s totally fine! The point of this post is to get you thinking about how YOU want to do your technical writing, not to force you to use my method!

That said, good luck and happy writing!