TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Evelyn Barker wondered: <<I'm going to be teaching a technical writing
class to junior-level university engineering students...>>
Which inevitably reminds me of a Robert Heinlein quote about trying to
teach a pig to sing. Something like: "It only frustrates you and annoys
the pig." <g> Okay, more seriously now:
<<... and wondered what the group thought it was important for them to
The biggest things by far:
1. Your audience is not composed of engineers, so you can't use the
same language you would use when speaking to your colleagues. Some
discussion of audience analysis would be appropriate: what words do
2. You are fascinated by features; they aren't. They just want to get
the job done. Teach them how to do that. Again, tie in audience
analysis: here, focus on a task analysis.
3. Don't write like an engineer. That's fine if you're writing a
journal article or engineering specification, but not if you're writing
to teach people how to do things. Here, discuss different styles (e.g.,
the difference between "distillation stack-mediated gas-exchange
cold-fusion separation product" and "a product that, using cold fusion
and a distillation stack, lets you mediate gas exchange" <g>).
4. Discuss real-world issues, like the need to do peer reviews (and the
great benefits from doing so: it's not just an exercise in masochism)
and how work with professional technical writers and editors.
5. Include a real-world exercise. I recommend documenting a VCR, since
(by the evidence) succeeding at this task escapes most real-world
technical writers. As an exercise, it includes both hardware and
software, and offers an opportunity to discuss the use of visuals. You
can also stretch out this exercise over the course of a full term, with
each component of the exercise tied to the current week's lesson.
Note: Although you can teach them much about "assumptions and how to
avoid them" with simple exercises such as "documenting the construction
of a peanut butter sandwich", many techies are enormously offended by
such seemingly trivial tasks that don't relate clearly to their chosen
profession. If you use such examples, do so purely as an introduction
to a more complex task (e.g., the VCR manual), emphasize that you're
doing it to illustrate a point that they can then apply to a "real"
example, and emphasize repeatedly that you're only using this exercise
to lead into a "real" example.
6. Teach them the "blueprint" principle: Nobody builds a house by
piling a bunch of materials on the ground and starting to lash them
together. Yet that's precisely how many engineers (particularly
programmers) do their job. Teach them the principle of "design thrice,
cut once": plan something with excruciating care, then test your plans
at least once (twice is better), before you actually start building.
(Here, an exercise in UI prototyping would help.) Sure, you'll have to
revise as you encounter obstacles, but at least that revision is much
less severe than in a typical design process.
<<I'm thinking that I should focus on communicating technical
information to a technical audience and that I should focus on the nuts
and bolts of concise writing.>>
I wouldn't necessarily say "technical audience"; though most of your
students will certainly have to communicate with their peers, most will
also have to communicate with nontechnical "persons of importance" such
as their managers, the marketing department, etc. (Think Dilbert!) In
terms of textbooks, there are many available. If your university
library stocks back issues of STC's _Technical Communication_, have a
look at the back issues. They contain many book reviews, and you can
almost certainly find something that sounds like it meets your needs.
--Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
ROBOHELP X5 - ALL NEW VERSION. Now with Word 2003 support, Content
Management, Multi-Author support, PDF and XML support and much more!
Now is the best time to buy - special end of month promos, including:
$100 mail-in rebate; Free online orientation on content management
functionality; Huge savings on support and future product releases;
PLUS Great discounts on RoboHelp training. OFFER EXPIRES March 31!
Call 1-800-358-9370 or visit: http://www.ehelp.com/techwr-l
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.