[pmwiki-users] Proposal: Recipe Structure Change

Tue May 23 09:26:35 CDT 2006

On 5/23/06, Tegan Dowling <tmdowling at gmail.com> wrote:
> This is where the PageTableOfContents recipe would really be useful.

I agree, a TOC when there are more than two top-level headings is my standard.

> Keeping all content on one page does have real advantages to "shoppers"
> (like seeing that there are problems with a recipe that doesn't live up to
> its "marketing", and isn't ready for general use)

This is where the "Community Review" section and the product summary
fits in. As an example, my Google Map API has been in my use for about
a year now. So, I listed it as "stable" in the recipe. Des noted there
were some outstanding issues I'd overlooked, so he revised the summary
to "development." This is _one_ place where the visitor would see a
potential problem. I tried to set up a sample format of what I'm
trying to propose (amended per Pm's hesitance to split beyond the
Discussion and Main pages).[1]

The "Community Review" is a section where people actually _rate_ the
utility of a recipe. Rather than bog down into a sea of swirling
comments and nested responses, the visitor sees: (Rating) (Signature
w/ Date) (Review):

   [+'''* * *'''+] Ben Wilson May 23, 09:01. Res ipsum loquiter, sed
quid in inferno decit.
   5 of 6 people found this review helpful.
   ''This review refers to version 1.0''

What happens now when a recipe does what it's supposed to but does not
live up to the hype? I believe it is ignored. There is no "review"
style commentary to indicate the utility. With a long page, this
presents a problem. Because of the likes of Amazon, visitors are
already familiar with the type of commentary suggested above. I go
into a little more discussion of this in the page I prepared for this
discussion.[2]

>  The drawback to one long page is...it's long, and often complicated.

I offer that this is a symptom of the problem. A page serving three
purposes, when at best it should serve one or perhaps two. If we adopt
a standard approach, then visitors will understand that while the
surface may appear calm (apart from a rash of negative reviews), that
the discussion page is where to find active discussion.

There are already pages that split themselves because they are too
large. CleanUrls, FixFlowSkin, Gemini-Skin, Pagelist, ToDo, just to
name a few. That is, others have already responded to one facet of the
problem in an ad hoc way. I am saying that all recipes should adopt
this approach to promote uniformity and predictability. The more we
follow this approach, the more new visitors will expect to find the
sales, technical, and commentary in reliable places. However, with the
three on the same page we have a higher degree of noise that may
distract.

The other problem people have is that there is no predictable way to
assess the popularity of a given recipe. They all sort of sit out
there without references. Adopting the Community Review as a standard
to the page layout gives a place for those who have tried or use the
recipe to rate that recipe. It also provides an identifiable approach.

Notice in this discussion itself the focus has been placed on the more
confrontational issue--that of splitting a page into two or three
related pages. There has been nothing said on the review. That's
because the discussion is meant to cover all the bases--but people
only see one. Had I split this into two or three different emails,
then the treatment of each specific point would be greater.

In the same way, having content that serves different purposes
detracts from the other purposes and distracts the reader. There may
be a rash of discussion on an issue--but a dearth of techincal. I
offer that we almost _never_ see a "review" of a recipe unless it is
buried in the Comments.

The Google Map API main page is three printed pages. The discussion
section is six printed pages, fewer if I redacted the past version
comments, then it would be fewer, but as this is a new recipe that
would be unfair. I believe having all nine pages on one page would be
too distracting.

[1]: http://www.pmwiki.org/wiki/Cookbook/GoogleMapAPI
[2]: http://www.pmwiki.org/wiki/Cookbook/ProposedRecipeStructureChange

> On 5/23/06, Joachim Durchholz <jo at durchholz.org> wrote:
> >   ...comments ... often contains
>
> a wealth of valuable tips and alternate approaches that the original
> author didn't think about. Splitting it off into a separate page
> increases the probability that visitors will overlook it - it's just
> that additional click away.
> Scrolling down is so much easier (and you can easier refer back to the
> actual recipe).
>
> This is where the PageTableOfContents recipe would really be useful.  I use
> it with all my installations and have never encountered an issue with it -
> could it be considered for the core and used by default on the cookbook
> pages?
>
> Keeping all content on one page does have real advantages to "shoppers"
> (like seeing that there are problems with a recipe that doesn't live up to
> its "marketing", and isn't ready for general use), as does having more
> structure  in the template, which helps a recipe's maintainer(s) and
> user-participants organize their contributions to the page in a logical way.
>  The drawback to one long page is...it's long, and often complicated.  You
> lose track of where you are and what's ahead.  A t.o.c. (and some
> template-included "back to top" links along the way) would help readers find
> their way around.
>
>
> _______________________________________________
> pmwiki-users mailing list
> pmwiki-users at pmichaud.com
> http://host.pmichaud.com/mailman/listinfo/pmwiki-users
>
>
>

-- 
Ben Wilson
" Mundus vult decipi, ergo decipiatur"