Re: Speaking of cookbooks...
...Who here has written a technical cookbook? I'm embarking on a cookbook project, and would like to hear advice etc. on what makes a good cookbook.
My cookbook is about using a very complex software for specific tasks, as well as some application tasks.
Here's my first rough cut at structure:
Task A
- Brief Description
- Procedure
- Tutorial
- Demo
- Code
regards,
karen
I recently published a technical cookbook (MySQL Cookbook, O'Reilly &
Associate; book site is http://www.kitebird.com/mysql-cookbook/). O'Reilly
favors a Problem/Solution/Discussion format:
Problem: state the problem to be solved
Solution: brief synopsis of how to solve it
Discussion: background on how the solution works or on stuff the reader
needs to know to understand the solution
O'Reilly has several cookbooks that use this style. You should be able
to find a number of them in the computer book section of any reasonable
size bookstore that has such a section. There's a sample chapter for
my book off one of the links at the Kitebird site, if you want to see how
I approached the problem of cookbook writing.
At 10:21 +0200 2/12/03, Erika Yanovich wrote:
Karen,
I know that according to fashionable theory, cookbooks are supposed to give exactly the amount of info needed to perform specific tasks - nothing more, nothing less. Personally, I find this annoying because after I perform the task according to the book I remain with nothing, no deeper knowledge of the underlying reasons/technology, no added value. I don't like performing a task without understanding why or how can I do it better next time. Cookbooks are for people who don't want to think - fish instead of fishing rod. So maybe you can add some links to other books/sources where this kind of additional info is available.
Erika
I'm unfamiliar with that fashionable theory; where does it come from?
It certainly wasn't the approach I took, which was that the readers ought
to understand why the solution to a give problem works the way it does,
*so that* they can apply the principles involved in solving the problem
to other similar or related problems they may have.
I think that characterizing cookbooks as for people who don't want to think
may do a disservice both to those who read them and to those who write them
(at least for technical cookbooks). A technical cookbook that was little
more than a "follow these steps to achieve the end result" isn't going to
be much good; no reader is going to have to solve exactly the same set of
problems in the book, whereas every reader is going to have to solve similar
problems, and thus will need to be able to apply the principles in the
book more widely. That's why it's important to emphasize not just what
to do, but why you do it and how it works.
I do agree that a technical cookbook written in the way you describe would
leave one with a feeling of "is that all there is" after reading it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
Follow-Ups:
- RE: Speaking of cookbooks..., Gerry Loiacono
References:
Speaking of cookbooks...: From: karen_otto
Previous by Author:
Re: Do as they say, not as they do
Next by Author:
Re: "Platform" vs. "OS"?
Previous by Thread:
Speaking of cookbooks...
Next by Thread:
RE: Speaking of cookbooks...
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads