• View
• Edit
• History
• Attach
• Print
• Backlinks

ProposedRecipeStructureChange

(Please contribute any comments to the Talk page.)

Problem

New users are having a difficult time sorting the wheat from the chaff regarding recipes. As somebody has said before, it is hard to tell which recipes are popular, active, and effective. This troubles some recipe authors as well. I mean, we have no way of knowing how well received a given recipe is. The comments may help somewhat, however we lack a "sales" approach to recipes.

Background

Today I received an email from Netflix. They were kind enough to remind me that my latest movie had been returned. I remembered that I wanted to add a movie to my queue, so I added it. Then, I looked at the page.

What is the purpose of a Netflix movie page? To inform the customer about the basics of the movie and entice them to add said movie to their queue for future viewing. This is accomplished via the following sections:

• At-A-Glance
• Enjoyed by Members who enjoyed
• Reviews

Look at Amazon's product pages. Basically the same approach.

• Glossy shot of the cover,
• Synopsis
• Customers who bought this item also bought
• Product Details
• Reviews

What is the purpose of a Recipe page? Threefold. One, to inform the visitor of a solution to a common problem he may be experiencing. Two, to provide the technical information necessary to help with installing, administering and using the recipe. Third, to allow two-way communication between users and the author to resolve problems, confusion, request features and offer improvements.

The problem is we have one page for three purposes. With the easy recipes, this may be enough. However, for the more involved recipe, we may need multiple pages. As I discuss below, we already do this for some recipes.

I submit that we should standardize an approach. Having such a standard will improve the visitor's expectation. He knows when he sees a recipe where to get technical information, where to read ongoing discussion, and knows that when he visits the first page he will receive concise information about the utility of the recipe from the author and other users in the form of review.

Compared to Amazon and We sort of already have the synopsis. The comments section is not so much a review as an ad hoc trouble-ticket system. We have the product details, but there is no uniformly adopted approach.

Proposed Solution

Change our approach to the Cookbook pages in a slight way. A given recipe page's primary purpose is to educate the visitor about the use and role of a recipe and sell him on how the recipe fills his need. PmWiki has grown strong in the Force these many months. We should exploit its strengths where it is most visible--the Cookbook.

First: De-clutter

Technical Information

Move the technical details into a separate page, perhaps Cookbook.SampleRecipe-Technical of Cookbook.SampleRecipe-Details

Move the installation process out of the recipe page for those recipes that have installations. Some are quick-and-dirty how-tos, so there is no installation per-se. The installation should go into the recipe's comments page, or in a recipe README file. If every recipe came with a "recipe.php" and "recipe.README."

• Move in depth discussion to a Cookbook.SampleRecipe-Details page.
• Move detailed examples to a Cookbook.SampleRecipe-Examples page.

An example of these two suggestions is manifest in the Pagelist Cookbook pages. These could be Cookbook.Pagelists (the main "sales" page), Cookbook.Pagelist-Details and Cookbook.Pagelist-Examples.

These pages could sort of serve as footnotes. If there's a potent example, it could be included via the markup. Otherwise, a simple link to the relevant example would suffice. "[[SampleRecipe-Examples#ex1|See Example]]." When pages must span pages (e.g. the Google Map API recipe), then there could be SampleRecipe-Example1, SampleRecipe-Example2.

Carve Out Discussion

Discussion is good. I hate to invoke the name a third time in two days, but MediaWiki has a point with the "SampleRecipe-Discussion" sort of Talk page.

Release Notes

The Release Notes could also be kept in a SampleRecipe-ReleaseNotes page. The latest release information could be included

Add Link Map to Cookbook.GroupHeaders

With all this de-cluttering, it would be hard for visitors to know when there is a discussion page to use, where there are examples, etc. We could put a map in the GroupHeaders, for example:

* [[{$FullName}-Discussion|Discussion]]
(:if exists {$FullName}-Examples:)
* [[{$FullName}-Examples|Examples]
(:if exists {$FullName}-Installation:)
* [[{$FullName}-Installation|Installation]]
(:if exists {$FullName}-ReleaseNotes:)
* [[{$FullName}-ReleaseNotes|Release Notes]]
(:ifend:)

Add Review System

Now that the pages has been denuded of technical information, what remains? Reviews by the users. This is different from the ad hoc discussion we common have on the recipe page. The main recipe page is the calmly sailing swan. The carved-out technical pages are the furious feet thrashing the water to move forward.

We include the types of review sections found in ecommerce sites:

• Related Recipes Used
• Alternative Recipes Used
• Community Reviews

Related Recipes Used

This is similar to "See Also," but would say "hey, this works well with. This section may be similar to a review as individuals would say what they liked. Naturally, when multiple entries like the same recipe, then they should share the list as much as possible. This shows a eye-ball tally of how well liked a combination of recipes are:

We use the following two recipes with this one:
* Deviled Eggs
* Fish Heads
** [[~BenWilson]] May 22, 2006, at 03:10 PM
** BubbaJones (no date)

I also like to use "Moldy Cheese" with this recipe. [[~BenWilson]] May 22, 2006, at 03:10 PM

Alternative Recipes

We also need to communicate to the visitor which recipe might be a better fit. A good example is Cookbook:UserAuth and Cookbook:AuthUser. Both serve the same purpose but in a slightly different way. This section would help communicate the trade-offs encountered.

Community Reviews

This section is geared toward a concise level of popularity with qualification. The concise level is provided via the "stars," and the qualification by a short summary of the rater's opinion.

First, you can put your stars in: * * * * (four stars) Yes, you even get zero stars. Diligence keeps a star from being moved up or down by someone other than the reviewer.

Second, people can edit to show whether they thought the review was helpful. Simple math: If you found it helpful" "x+1 out of y+1 people found this review helpful." If you did not find it helpful: "x out of y+1 people found this review helpful." Diligence can prevent fraud (somebody doing X+23 out of y+20).

• 117 out of 124 people found this review helpful.

:[+'''* * * *'''+] '''A Great Idea''' [[~BenWilson]] May 22, 2006, at 02:49 PM:Etiam auctor turpis vitae arcu. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nulla dictum vehicula elit. Cras imperdiet, ante vulputate facilisis ultrices, nisi libero laoreet metus, at elementum neque odio vitae arcu. Vivamus orci. Phasellus tristique aliquet orci. Cras at ligula non purus tincidunt suscipit. Suspendisse cursus est at purus. Curabitur egestas purus vitae elit. Morbi sed massa. Sed mollis condimentum risus. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Mauris justo. Vivamus consequat euismod libero.
* 37 out of 38 people found this review helpful.

:[+'''* *'''+] '''Terrible''' [[~BenWilson]] May 32, 2006, at 02:49 PM:Etiam auctor turpis vitae arcu. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nulla dictum vehicula elit. Cras imperdiet, ante vulputate facilisis ultrices, nisi libero laoreet metus, at elementum neque odio vitae arcu. Vivamus orci. Phasellus tristique aliquet orci. Cras at ligula non purus tincidunt suscipit. Suspendisse cursus est at purus. Curabitur egestas purus vitae elit. Morbi sed massa. Sed mollis condimentum risus. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Mauris justo. Vivamus consequat euismod libero.
* 37 out of 38 people found this review helpful.

Third, you get your opinion in.

A Recipe for Ratings

We have to edit the page to put in the stars and the helpfulness. If we had a recipe to count the stars, we could do something like:

 (:rating-total:) (which in this example would return [+'''* * * *'''+]

 (:rating-2:) (which would return [+'''* *'''+])
 (:rating-5:)
 (:rating-1:)

  function RatingsAverage($ratings=array()){
    $total = 0; $count = count((array)$ratings);
    foreach ($ratings as $r) $total += ($r > 5) ? 5 : $r;
    $rating = (int) ($total / $count);
    $stars = str_pad('', $rating, '* ');
    return array($stars, $rating);
  }

Organization

• Summary (what is presently appearing at the top of pages.
• Purpose Statement (what's the problem and how does this recipe solve it?
• Technical Details (the recipe file itself and other key information. This may be redundant with the Summary). Will also refer to examples.
• Other "Collocated" Recipes
• Preferred Alternative Recipes
• Community Reviews
• Release Notes

#1 1: See Cookbook:PagelistExplained? and Cookbook:PagelistTemplateSamples BenWilsonMaintained Obsolete