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.
Subject:If you had to teach (Take II) From:techwriter -at- supalife -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 28 Mar 2002 11:47:22 +0000
Lucky, lucky me. I'm getting to run a workshop to train our project managers
how to write user manuals. And you're all invited (to help).
After the workshop, for every project they release, they will be expected to
produce user guides (for two different types of user) and data set-up/config
I want this workshop to concentrate on getting the right information out of
them in a way that resembles a user guide, instead of the computerese or
expertese (hey, good word!) that they currently produce.
Because this list is excellent and Tom asked a similar question earlier this
month I already have half an answer.
For the user guide, I'm intending to provide some really bad instructions for
making a sandwich and sit back and laugh as they try to make this sandwich
without knowing where the bread is. We would then work from the problems
encountered in the bad instructions upto the pre-prepared (sorry Stan!) model
1. Select Carrier Bag > Bread...
Likewise for the data set-up/config guides we'd go from some bad description
through to a model answer, something like...
Fillings are fully configurable. Valid values are Cheese, Jam, Salad. You can
select more than one Filling.
Warning! The system does not validate your selections so do not select nasty
I was also thinking of putting this in the context of a Going on Picnic (it's
nearly a long weekend -- whaddayawant?) where you would be Making Sarnies,
before Loading the Car, and even if the Packing a Hamper functionality was
done three releases ago I want it in this user guide because this is the one
I'm reading (and preferably between the sandwich-making and the car-loading
I've written a style guide. I've also created a template for each of the doc
types, that use a toolbar that contains every formatting command they could
ever need (Want Bullets? Click the button that looks like a bullet...) and
I've written instructions for using the templates, so I was hoping to keep the
Word and word elements of the workshop to a minimum (beyond the obvious
Consistency is Good and Know thy Audience blah).
What have I not thought of? Will this work? Will this work only if I let them
eat the sarnies? So would it work better with pizza? Any advice, tips or help
would be hugely appreciated (other than the 'runaway' ones that Tom got --
sadly that's not an option!)
And if any of you are having a Friday early and want to try your hand at bad
instruction writing, I'd appreciate it -- it's really hard!
PS And yes I know. I'm not sure training twenty other people to do my job is
PC Magazine gives RoboHelp Office 2002 five stars - a perfect score!
"The ultimate developer's tool for designing help systems. A product
no professional help designer should be without." Check out RoboHelp at http://www.ehelp.com/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.