RE: Tech Writing Curriculum

Subject: RE: Tech Writing Curriculum
From: "Jane Carnall" <jane -dot- carnall -at- digitalbridges -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 12 Nov 2001 17:27:04 -0000

1. Interviewing technique. How to get as much information as possible in
strict segments of time and how to take usable notes, from an expert who
knows their subject but may not be very articulate about it. Students may
use doughnuts and chocolate as required.

2. How to read design documents and specs, code comments, javadoc, etc: the
kind of information that SMEs create for each other. How to run an Internet
search. How to ask the right kind of question on Techwr-l...

3. How to structure and plan out an assignment, chapters, sections, and
sub-sections, indexes, TOC, front matter: and how to figure out which bits
of whatever it is you're documenting aren't going to change, and which bits
are, so as to do the unchanging bits first...

4. Software tools. What's needed is (IMO) not so much learning the ones in
current use (after all, they may not be in current use next year, except for
MS Word...) but the process of learning lots of different software tools.
Make them learn a different one every week, and switch from one to another.
Tell them which software tool they have to use for each assignment, and no
appeals of "but it's much easier if I use XYZ" should be allowed. Students
should specify what software they already know how to use at the start of
the course... and should never be allowed to use it for the duration. (For
added realism, they could be told to switch tools in the middle of the
assignment...)

5. How to deconstruct a situation into the relevant pieces and put it back
together again in a logical order. The "situation" could be anything:
hardware, software, history, a peanut-butter sandwich or a cup of tea*: it's
the habit of structured thought and ability to summarise and create order
out of chaos that (IMO) a technical writer should inculcate.

6. Technical writing style, which will look very crude and boring to anyone
who's been studying English literature. Consistency and repetitiveness (if
you have the same thing to say in six places, it's okay to say it exactly
the same way each time), one idea per sentence, avoid complex sentences, use
the right vocabulary for the subject, all that kind of thing. It's true
(before anyone else says it) that a good technical writer can write clearly
and simply and make it read well: but I think it's worth emphasising that
the first priority (after technical accuracy) is clarity: that no one reads
a technical manual the way they do a novel. (Well, except us, maybe.)

Jane Carnall
Technical Writer, Digital Bridges, Scotland
Unless stated otherwise, these opinions are mine, and mine alone.

*Yes, I'm serious. If enough companies still use "How to make a peanut
butter sandwich" (US) or "how to make a cup of tea" (UK) as their initial
writing tests, this course might as well show students how to pass them...
<g>


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -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.


References:
Re: Tech Writing Curriculum: From: Win Day

Previous by Author: RE: New TECHWR-L Poll Question
Next by Author: RE: OT RE: Tech Writing Curriculum
Previous by Thread: Re: Tech Writing Curriculum
Next by Thread: RE: Tech Writing Curriculum


What this post helpful? Share it with friends and colleagues:


Sponsored Ads