[pmwiki-users] Summary lines in cookbook recipe info

[Patrick R. Michaud]

On Wed, Apr 18, 2007 at 04:25:20PM +0000, Sandy wrote:
> It is possible to condense the 6 lines into much less.
> [...]
> One possibility:
> Acme (alias ZAP). Advanced forms processing, member and file management, 
> page editing and insertions, newsletters, shopping cart.

Sandy proposes exactly what I was going to suggest -- namely, 
to shorten the description down to the main capabilities provided
by the recipe and without non-distinguishing terms such as
"powerful", "extensible", "many more", "much more", etc. [1]

I disagree with the phrasing of "one recipe page for each
distinct recipe" as described in [2].  

A recipe is a description of how to accomplish a given task, 
and substantially different tasks deserve their own pages.
(If PmWiki were a "recipe", then the approach described in [2]
would seem to indicate that we try to describe everything in 
a single page, which is obviously not what we want.)

If the separate pages describe sufficiently distinct tasks,
then to me it's okay for them to exist as separate pages even
if they all rely on a common script or engine. However, they
should probably tend to exist in separate categories -- for example,
all of the Fox* recipes seem to appear in the "forms" category
even when what they are describing isn't really about forms.
I wouldn't classify FoxVotingList or FoxBlog in the [[!Forms]] 
category -- yes, they use forms to do the work, but they aren't
about forms, nor is someone looking for those capabilities
likely to be looking in the "Forms" category.

It's also valid to create custom categories (e.g., [[!Acme]]
or [[!Fox]]) for pages related to those engines.  Or just use
link=Cookbook.Acme and link=Cookbook.Fox .

If the number of recipe pages reach the point where there are
a lot of closely related pages in a single category, it's probably
time to look at separating documentation (how it works) from 
recipe (how to do things), and putting things into their own
wikigroup(s).

If we really need a policy statement from me about the Cookbook,
my policy is to do whatever makes things easiest for newcomers.
That generally means short and precise descriptions, avoiding
superlatives, and respect for the impacting that a particular
recipe (or set of recipes) might have on the overall structure
of the Cookbook.

Pm

[1] I'm not saying that Acme isn't powerful or extensible, only
    that these terms are meaningless in an environment where
    many things are powerful and extensible.

[2] http://www.pmichaud.com/pipermail/pmwiki-users/2007-April/041884.html