[pmwiki-users] Does this list inhibit development of good documentation?

[The Editor]

On 3/6/07, Dr Fred C <drfredc at verizon.net> wrote:
>
>  IMHO, this is where the problem really lies.  A fair amount (but not all)
> of cookbook documentation provides little to no workable examples of the
> cookbook features in actual use.  Instead, everyone basically has to
> reinvent the wheel over and over, which requires attempting to comprehend
> the documentation.  Where documentation lacks good examples, the
> documentation tries to explain relatively simple stuff using jargon rather
> than by example (plus jargon).  It's like you trying to tell someone how to
> get dressed with both of your eyes closed and they must follow your
> instructions literally.  This simple process typically ends up a tangled
> mess.  However, once one figures out how to do it, magically everything
> starts to make sense and you're ready to move on.  Go figure.

Not sure I agree...  I had the same complaint with zap so I put up
about 40 sample snippets, and a bunch of documentation on the various
commands, with comments, etc.  Still, kept getting questions and even
complaints--because people couldn't figure out how zap worked.
Finally I put up several pages of general info, giving an overview,
and now I rarely get anything but specific questions about specific
applications.  I think that's what we need with PmWiki.

There is a lot of good documentation up already, but I remember when I
started, not understanding at all what went in a config file, what
went in a wiki page, how everything fit together, etc.  I posted
several requests for a good primer and never got much info--though I
had bunches of questions answered.  Questions I see others still
asking today.  So I think a good overview of how PmWiki works would be
helpful.  No time to write it myself, so I'm not complaining.  Just
adding my two cents.

Cheers,
Dan