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.
The main thing I'd add to Karen's structure:
>
> Task A
> - Brief Description
> - Procedure
> - Tutorial
> - Demo
> - Code
>
is a picture showing either the expected result, a contextual diagram, or a
flowchart. I call this the "Betty Crocker Recipe Card Approach." Those cards
use a picture to help users select the appropriate procedure and see what
the end product is supposed to be. Very useful, IMHO.
Chatty cookbooks, like _Laurel's Kitchen_ and The Frugal Gourmet series are
fine in their place. They give background (including whys and wherefores and
possible substitutions), context, and stories that users can relate to.
They're annoying as all get out if you're in a hurry to get dinner on the
table. If you do go the "chatty" route, at least mark the procedural pages
with bleed tabs or something so theyre easy to find.
I still love my mother's 1940 _Boston Cooking School Cookbook_ by Fannie
Farmer. It's well used and marked up with priceless notes, but the main flow
of the recipes is unimpeded. Its one drawback, from a tech writer's
standpoint is the assumptions it makes about the user's knowledge - for
example, a tendency to say things like "preheat oven to hot," and "cook
until done..." things that a 1940s cook probably would have known. I also
have a great recipe for shredded-wheat bread, scrawled on a scrap of
pocket-notebook paper during a camping trip. The instructions are minimalist
in the extreme, but I fill in the gaps from my existing knowledge of the
process. In your technical cookbook, you have to be more specific about
these things.
For a friend who finds fractions challenging, I wrote up a favorite recipe
(for hermits) in the form of a table, with the proportions spelled out for
doubling, tripling, and quadrupling the original recipe. She was very
grateful. It keeps coming back to "know your audience."
Wow, that was a rambling excursion. Now back to work!
Marguerite
Buy or upgrade to RoboHelp X3 today and receive the WebHelp
Merge Module for FREE ($299 value). RoboHelp X3's all-new
features include conditional text, completely re-engineered
printed documentation output, Context-sensitive Help Toolkit,
single-source layouts, and more!
Order online today at http://www.ehelp.com/techwr-l
---
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.
