[pmwiki-users] want opinions on a new cookbook recipe format

[Patrick R. Michaud]

On Mon, Mar 06, 2006 at 08:12:26PM +0100, Joachim Durchholz wrote:
> pmwiki at ben-amotz.com schrieb:
> > In any event, the exercise
> > of restating a recipe in practical terms of a question and answer can
> > help focus the author on the intended audience and the bigger picture
> > (rule 3, for example).
> 
> The downside is that it tends to focus the author (or the reader) too 
> narrowly, to one of multiple possible uses.
> 
> (I'm not sure whether this is an argument for or gainst the Q/A format.)

I can see many sides to this.  Jo is quite correct that there are
often recipes for which the Q/A format doesn't make sense -- I've
run into that problem myself at times.  However, being able to phrase
the recipe in response to a question or two does really help a new
reader to know "is this recipe going to do what I want"?

How about an optional "Common questions answered by this recipe" 
section at the top, immediately following the summary/status/etc. 
lines but before the description?  This would be an easy place to help
people orient themselves to the recipe, but it could be omitted for
recipes where it doesn't make much sense or simply repeats the
summary.

See, for example, the latest version of 
http://www.pmwiki.org/wiki/Cookbook/RandomQuote .  I think it
works reasonably well.

Pm