I am currently on a committee looking to set some standards for technical writing in the introductory engineering sequence (which means the first two terms of physics, as they constitute 50-67% of the classes common to all first-year engineers). One of our jobs is to come up with a list of skills that we want to particularly emphasize in student writing in the first year.
I've already sent this query to my colleagues, who are the votes that really matter, but this seems like a worthy subject for a blog poll. If nothing else, it will be interesting to see if my wise and worldly readers prefer to emphasize different things than my colleagues on campus.
The following is a (condensed) list of characteristics of technical writing. Which of these do you think is the most important for students in the intro physics/engineering sequence to learn?
While these are all important, I'm looking for your opinion of the most important single item, so choose only one answer. Unless you'd like to vote multiple times from different computers...
- Log in to post comments
I'm a professional technical writer (Quality Systems, Safety Programs). I would also include on your list
Language that supports objectivity.
I would have voted for the bullet points except for the word 'May'. I would change that to 'Must'. Far too many writers group write lists in the form of paragraphs and that makes them hard to make out (and to find later for reference!).
"May use bullet points" is not really a universal feature of good writing, technical or otherwise, and it seems like a strange thing for a course to focus on. Bullet points are good for some types of writing (e.g. a slide presentation), and not really done in others (e.g. peer-reviewed research paper). If this is a course on technical slide-shows, that's fine, but if the goal is to teach general technical writing, it's not.
Likewise, "may use passive voice" and "Written in a style close to spoken language" and "organized to allow nonlinear reading" are situational things which may or may not be appropriate for any given piece of tech writing. Teaching them as "the way to do tech writing" will only give the students bad habits that they may have to unlearn later.
OTOH, "empirical, specific, and accurate" "overall organization" and "use of visual elements" are *skills* which can and should be applied to any piece of technical writing.
Take a look at Writing Across the Curriculum.
http://wac.colostate.edu/intro/
As a former tech writer/editor, I'd say that the most important thing is that use of the document must be tested for ease of use, logic, and comprehension by a sample of the intended audience.
Also, not just use of charts, graphs, equations, but actual illustrations where appropriate.
Another pro tech writer here (mostly CAE and FEA).
Audience analysis is the single most important thing in technical writing. Audience analysis tells you the difference between what your audience already knows and what your audience needs to know. If you know your audience well, that knowledge will drive all your other decisions. The rest is craft.
Organized to allow non-linear reading; repeated information so sections "stand alone"
The word you're looking for here is "topic-based."
There are differences between scientific and engineering technical writing. Scientific writing is, by nature, descriptive where engineering writing can be either descriptive or prescriptive (at a minimum.)
Speaking after a wholebunchayears in standards work, the engineering students need at least an introduction to prescriptive writing. Language for specifications, for instance, has a very constrained set of terms: "shall" "shall not" "may" and "may not" for instance are not optional phrasings. Like any skill it takes followup and practice to actually become proficient in prescriptive writing, but a foundation covering the key points is necessary just to make sense of common documents.
Overall organization is definitely the most important skill. Precise language and use of visual elements can make a well-organized document easier to read, but if the document is poorly organized, none of the other elements will help. Knowing your audience is a close second (avoiding flowery or ornate language is part of that; e.g., most people who grew up in Asia and are not specifically trained in the subject will not have the exposure to Greek mythology that educated Westerners are expected to have acquired).
As others have pointed out, some of these pointers are definitely context-dependent. Bullet points make sense in a summary, but where you actually need to defend your points to a reader, you need to include some prose. Likewise, in some journals passive voice is still preferred, but others do not mind first-person pronouns (the avoidance of which is a leading cause of passive voice in papers). People who are writing a reference document need to write sections that stand alone, but reports and scientific papers generally don't need stand-alone sections.
Usual unhelpful answer:
Maybe at your fancy-pants institution this question makes sense, but I'm happy whenever I have a student that can reliably crank out grammatically correct sentences and write coherently.
It never crossed my mind to try to push a certain style, but I suppose the penultimate choice of "overall organization" and "logical progression" is a good idea. It's certainly a worthwhile exercise for the author.
Know your audience and write for them -- but even in texts intended for specialists, provide "handholds" for people not quite up to the specialist level of understanding. Define terms which might be confusing. Oh, and in charts and graphs don't assume your reader knows what the units of measurement are -- I hate charts where no units are listed or they are equivocal. This is commoner than I would have expected.
And as a hint -- before finalizing the piece, read it out loud and if possible get someone else to read it out loud. Awkward passages or logical gaps can hide on the page more easily than they can when spoken aloud.
Noni
I'm a professional technical writer (in software), and I am with HP -- the most important skill in technical writing (or really any non-fiction writing) is audience analysis. If you can teach your students how to target different groups with their information, everything else is, as HP said, craft.
An exercise I've used in postsecondary writing teaching is to have students do a short piece of writing using the same basic set of facts (which you provide) aimed at two different audiences (which you also specify). If you're doing this in a community-college or first-year scenario, you can have the students brainstorm in groups.
My vote went to the "no flowery language". You can teach a lot of the other points with a well-done template, but it's so hard to get them to stop using words you need to check in a thesaurus to understand. And in 75% of the cases the words don't mean what they want to say, inconceivable!
In my experience, one of the most common mistakes rookie science and technical writers do is that they use the passive voice too much, not too little. It's an easy way to make anything sound authoritative, and insecure writers will cling to it like a lamprey to a corpse. Also students are wary of putting their necks out, so saying "the data was analyzed using ..." feels safer to them than saying "we analyzed the data with ...". cf "Mistakes were made" rather than "We made a mistake".
And of course, the passive voice is harder to read for anyone, and very difficult to parse for many second-
or third-language learners of English (this goes for similar constructions in other languages too). Whenever you overuse the passive voice you lose part of your readership.
Teach them to use it less, not more.
Along with a third (fourth?) for the "audience analysis", when I'm doing CMS project objectives for writing outcomes (as opposed to the technical stuff around how the XML gets mangled) I tend to use the four C's -- correct, complete, clear, and consistent. (Concise isn't a virtue if it messes with any of those four, so it's not the five C's.)
But really, knowing how to figure out what your audience already knows is key. Really brilliant writing to the wrong audience isn't helpful; OK writing to the right audience is.
I picked "empirical, specific", but I'm glad to see close-second choice of "organized" got ranked above it. I didn't like the reference to graphs or tables without the adjective "appropriate" added to it! IMO, the thing that was really missing was "follow directions", although that might be less of a problem at a SLAC than elsewhere.
I think the most important thing is for them to identify the key result and report it accurately and succinctly, with uncertainties and units, preferably with a separate conclusion about the reliability of the results.
My suggestion, along the lines of @5, @10, and @11 is to use the students as the audience. Students can even learn to use a rubric to evaluate blind (numbered) copies of a report, and learn how to do a better job on their own report as a result of the feedback on their own and what they saw when reading other reports.
PS - As I thought, something you wrote in the past prompted me to write some thoughts from the laboratory perspective a few years ago. Here it is
http://doctorpion.blogspot.com/2008/06/lab-writing.html
I hope that you follow up on what you decide. I'm one of the English teachers who teaches the tech writing class. Consider document design, incorporation and explanation of visual features, and writing across media (increasingly important).
HJ
About that passive voice thing. The 2 tech writing classes I've had both forbid passive voice. And a damn good thing too. Surgically remove it from pretty much everybody. By force if need be.
No, really. I once re-wrote and entire manual for hospital volunteers which had been written entirely in passive voice. Because the previous writer had thought that more polite. It's wordier than active and more confusing.
Brief, to the point, clear, active voice.
MKK
Maybe i misunderstood your listings, but it seems to me that the standard format (science report or dissertation chapters) is a very good way to introduce students to an accepted format for laying out the results of a scientific investigation. Once students learn how describe the definition of a problem (including operational definitions), previous work done in the field and rationale for current investigation, current hypothesis, data collected (described in words and pictures)and final conclusions as well as future directions--it would be a huge boon to anyone who has to practice communicating about scientific work.
Technical writing is way more complicated than formatting reports or avoiding passive voice. Consider referring to the wealth of research and scholarship in the field of technical communication. Good journals to look at include Technical Communication, Technical Communication Quarterly, IEEE Transactions on Professional Communication, the Journal of Business and Technical Communication, and the Journal of Technical Writing and Communication. One often-cited article on tech comm curricula is by my colleague, Kelli Cargile Cook: "Layered Literacies: A Theoretical Frame for Technical Communication Pedagogy," Technical Communication Quarterly 11 (2002): 5-29.