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.
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
---
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.
