In this post I am going to talk about content preening, as this is where we all typically have the most to learn. Ensuring quality of content is undoubtedly the most difficult aspect of technical writing; it’s a problem I see in every single technical document I review. I even see it in most of my own early manuscript drafts. (I imagine my colleagues see it in my late drafts, too! :-)) Like every other aspect of good technical writing, there is nothing magic about getting this right. Any of us can do it well – we just need to make the effort.
One of the most important characteristics of good content is relevance. Before you include any sentence, paragraph or section in your document, consider why it is there. Does each sentence offer new and specific information supporting the topic sentence it appears with? Does each topic sentence refer to a concept that is relevant to your overall message? You can see why proper ‘paragraphing’ is critical to ensuring the value of content (see my post on proper paragraph writing if you need a review on those skills). However, that’s not where it ends. You need to ensure relevance at the section level, as well. One way to achieve this is to avoid the narrative style of writing; it’s generally chronological in nature and relatively unfocused. Consider the following (thankfully fictitious) example of the narrative style.
“For each experiment I first turned off the lights it the lab so that the laser would work better. It worked better in that I got better images with the digital camera if the room was dark. Then I filled the coffee pot and put it on. I would then start up the pump for my flume and boot up my computer. Then I would fire up the laser and check the alignment since I’ve forgotten to do that a few times and had to repeat the test. Once the flow was going good in the flume I would add some seed particles. I would then look in my notebook to see what tests I had run before so that I could do a new one this time. I did do three repeats of each experiment though.”
No doubt we can all relate to, and sympathize with, the more tedious aspects of experimental research but do we really need to know most of these details? Nope. Also, the tone is quite conversational and casual in this example – something you should definitely avoid in technical writing. I am not suggesting that you be overly formal and flowery, but a conversational tone is often unnecessarily wordy and generally not particularly factual, especially when combined with the narrative style. Instead, aim to write topically – break down the content into logical technical units, regardless of when they were done. What we want in this example are the key steps in the experiments. First what was the plan? What suite of experiments did you run and why? Be specific in describing the parameters of each experiment; for example in this case some important physical parameters might be: flume slope, flow depth, flow rate, seeding density, camera position, lens aperture, shutter speed and image sampling rate. Certainly describing the methodical steps in each experiment (the “experimental protocol”) will be somewhat narrative, but try to avoid including details that would more suitably be grouped with “putting the coffee on” as irrelevant information.
How can you spot irrelevant text in your thesis or report? Generally it is full of adjectives, imaginative descriptions, repetition and/or commentary. Search out and delete all of these vague and meaningless phrases, sentences and paragraphs. Remember also that qualitative descriptions are generally useless. For example:
“lt was found that the various models produced similar results.”
Your reader is justified in wondering: ‘which models’ and ‘how similar? A more appropriate approach would be to name each model specifically and then quantify the percent differences in some key output value(s). You could even provide a comparative table or graph. (Don’t forget to quantify measurement and modeling errors, as well!)
Commentaries, especially descriptive assessments about the quality of your data and research, have no place in your technical document. If it’s excellent, your reader will let YOU know. Also, don’t use ten words if three will do. Writing in a compact and efficient manner will not only keep your reader with you to the end, it will also help to prevent ambiguity. It’s sometimes helpful to think of each word, sentence, and page as an item which costs you money. In fact, it’s true. Whether it’s duplicating your thesis, torturing your defense committee or meeting publication length restrictions when submitting a paper to a journal, in technical writing — every word counts! So, for your final draft, screen out the repetitive and wordy descriptions; this will help to make the final product as articulate as possible.
In my next post I will provide some advice on how to use figures and tables effectively…
P.S. don’t worry – it’s only a toy… 😉