[pmwiki-users] Proposal: Recipe Structure Change

Ben Wilson dausha at gmail.com
Mon May 22 15:48:06 CDT 2006


To keep this email brief, I have put more thought into how to approach
improving documentation.[1] Specifically, I have focused on the
Recipes. I offer that we currently apply three distinct purposes to a
given recipe page when we should have the main page serve only one
purpose. Because of these divergent purposes, the pages tend to under
inform the visitor by trying to address all concerns simultaneously.
We should break the three purposes into separate pages. By breaking
the purposes up, we focus the visitor's attention on the category of
information relevant to the recipe that he wants.

The purposes: "selling" the recipe, providing technical information,
communicating feedback.

The main recipe page should sell the recipe. This is because a visitor
will first want to know if the recipe even works for him. Our current
approach undersells the recipe by focusing too much on the other
purposes. While this may suffice for those of us with legion
experience in PmWiki, this may put-off our neophyte comrades. To grow
the community we should put more emphasis on selling our strengths,
which is a receptive code base and well-written recipes that pack a
punch.

There should be a separate technical page for the minutia and another
page for discussion. The technical and discussion pages are fairly
self-explanatory. My focus is on the "selling" portion of a recipe,
which (IMO) is lacking.

What the "Selling" page addresses:

* Focus on the problem and how the recipe solves. We have
  this now, sort of. I'm personally very bad about this. By having
  one page dedicated to this, the weaknesses in this regard will
  stand out more clearly, as there will not be the technical
  information to obfuscate.

* Offer community input on which recipes work well with a
  given recipe. For example, Cookbook:HtpasswdForm
  works with Cookbook:AuthUser.

* Offer alternative recipes. For example Cookbook:AuthUser
  and Cookbook:UserAuth.

* Offer Community reviews to resolve the "how popular is
   this recipe?" question by showing stars and a concise
   explanation.

In my discussion, I compare the "selling" page to Amazon and
Netflix--ecommerce. Hey, if they can sell online, we can learn a
lesson.

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

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




More information about the pmwiki-users mailing list