[pmwiki-users] pmwiki documentation: Edit Templates

[Patrick R. Michaud]

On Wed, May 24, 2006 at 11:16:44AM -0400, Curtis, Clayton wrote:
> I hope this discussion continues (and leads to a more accessible
> documentation set).  I really respect all the work that goes on!!!  But
> I am definitely in the camp of "it would help a lot to have things from
> the cookbook that pertain to the core in the core documentation".  I'm
> not sure whether the "too much documentation" view derives from impact
> on download / storage (which I kind of doubt) vs issues with how it's
> organized and how easy it is to comprehend it.  I definitely get the
> issues of overlap in types of content and the fuzziness of audience
> definition, but to me that's just more ammunition for NOT separating
> Cookbook content that is core-related from documentation about the core.
> (Sorry for the long post, but this one hit a nerve as a newcomer trying
> to understand an incredibly rich tool set.)  

The Cookbook is intended to be more task-oriented -- i.e., "how do I
accomplish XYZ in PmWiki"?  The core documentation is intended to
describe the basic setup of a standard PmWiki system.

I'm pretty sure that simply moving information from the Cookbook 
into the core documentation (i.e., the PmWiki group) would not 
by itself make it any easier to locate things.

Put another way, simply describing all of the configuration
possibilities that are possible purely within the core would easily
double the current size of the documentation.  And in order to be
useful, it probably needs to be task-oriented anyway (i.e., "how do
I do XYZ"), and for this the Cookbook seems like a much more useful
organizing framework.

That said, I'm very willing to be proved wrong on these points, and
there's absolutely no prohibition to moving information from the
Cookbook into the core documentation where it's appropriate to do so.
I've just found that it's not always easy to figure out where something
should go in the PmWiki documentation, or how to add it without
making a page overwhelming in its scope and/or detail.  (This is
an advantage of Cookbook recipes -- they can be fairly focused to
a specific task.)

Pm