[pmwiki-users] Documentation of Recipes (Eemeli Aro)

John Rankin john.rankin at affinity.co.nz
Thu Jan 22 22:25:11 CST 2009


On Thursday, 22 January 2009 11:23 PM, Eemeli Aro <eemeli at gmail.com> wrote:
>2009/1/22  <john.rankin at affinity.co.nz>:
>>> I'll accept the argument if you (or someone else?) can give me at
>>> least a couple of examples.
>>
>> http://www.wikipublisher.org/wiki/Cookbook/Cookbook
>>
>
>Ah, ok. I was wrong. Or at least presented my opinions incompletely.
>And indeed I didn't mean that "only one obscure site" could or should
>be ignored. Here's a more complete account of my view on including
>Cookbook documentation in local storage.

Phew! Plus we don't know what happens on private wikis behind firewalls
(no doubt between consenting adults).
>
>...
>really, the name doesn't matter. I do, however, shy away from
>constructs such as "PmWiki.Cookbook-RecipeName", as these add an
>unnecessary third level to this page hierarchy. How about
>"PmWikiCookbook.RecipeName"?

Heh! That was my other alternative. The reason I didn't suggest it
is that we know to avoid PmWiki as a group name, as it's "reserved 
for PmWiki stuff". But if we generalise the rule to "groups called
PmWiki* may be used for PmWIki stuff" then I agree with you that
PmWIkiCookbook is preferable.
>
>As for the location in which to put these files, how about the
>wikidoc.d directory PM mentioned sometime earlier? Or if we leave that
>for just PmWiki documentation, adding them to wikilib.d might be
>easier. Adding a new PageStore seems rather wasteful, except if
>there's extra functionality that requires it.

I prefer a directory that is not likely to be over-written by an
upgrade (possibly inadvertently). So I support either a wikidoc.d
(if the recipe author is distributing a single page, which may 
well cover most cases) or a cookbook/recipe/wikilib.d 
(if the recipe includes several pages).

I also agree with your comment that distributing pages with a
recipe is a practice to think twice about. However, there are 
legitimate reasons, including:

- pages required to drive a recipe, such as form templates

- documentation aimed at content authors (administrators may be 
  happy to read the Cookbook.Recipe page, casual authors less so)

To help content authors discover recipes' user documentation, it is 
much easier if there is a convention for recipe authors to follow.
PmWikiCookbook.RecipeName works fine for me!

>...

JR
-- 
John Rankin
Affinity Limited
T 64 4 495 3737
F 64 4 473 7991
021 RANKIN
john.rankin at affinity.co.nz
www.affinity.co.nz





More information about the pmwiki-users mailing list