RE: Speaking of cookbooks...

Subject: RE: Speaking of cookbooks...
From: "Marguerite Krupp" <mkrupp -at- cisco -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 12 Feb 2003 09:54:55 -0500

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!


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

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 for more resources and info.

Speaking of cookbooks...: From: karen_otto

Previous by Author: RE: seeking good design doc formats
Next by Author: RE: Calling All Cooks & Design Gurus
Previous by Thread: RE: Speaking of cookbooks...
Next by Thread: RE: Speaking of cookbooks...

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

Sponsored Ads