[pmwiki-users] suggestion for continuously improving PmWiki documentation

[Neil Herber]

At 2005-01-28  01:52 PM -0600, Patrick R. Michaud is rumored to have said:
> > I really like your idea of a Q&A page. I would go so far as to suggest a
> > new group: PmWiki/Questions
>
>Er, I hope you mean "PmWikiQuestions" for the group name.  :-)
>
> > For example, I could post my question about cron jobs for PmWiki under
> > Windoze to PmWiki/Questions/CronForWindows.
>
>PmWiki (and certainly pmwiki.org) doesn't do multiple-level-hierarchical
>names.  :-)


Sorry! What I meant was wiki/Questions/CronForWindows, where "Questions" is 
a new group name.

> > Although they might not stumble on the page immediately, anyone doing a
> > search for "cron" should find it.
>
>We've had several attempts at building a PmWiki.FAQ document, but somehow
>it gets a bit too unwieldy to work with as a single document, and when it
>got split up into separate documents it wasn't always obvious where to ask
>the question (or how to find it).  Having each question as a separate
>document is a possibility.  But any time we add more places to look for
>information, we run into the problem of giving ourselves even more places
>to look for the information (without a good guide or roadmap for where to
>look).

Perhaps my initial suggestion has been lost in the fog generated by my 
secondary suggestion.

I want questioners to add their questions with answers (a concise version, 
not just a dump of a bunch of email) to what I called the "appropriate 
page" - generally the page where the questioner hoped to find the info (and 
did not) or the page where the question was answered in a manner not 
obvious to the questioner. A suitable heading might be "How I finally got 
this to work" or "I was confused by this until ..."

In this way, we can easily identify pages that are being misunderstood or 
that seem incomplete to users. An author more skilled than the questioner 
might incorporate the added material directly into the original page. Note 
that many new users, myself included, are *very* reluctant to edit 
"official" documentation.

Menachem's suggestion (and my secondary remarks) had to do with ways of 
accommodating lengthily discussions that might make the initial page too 
unwieldy. A link from the original page to the discussion/example/qustion 
page would be all that was needed, and would give users a path to follow.

>Much of the Cookbook is designed as a "FAQ" resource -- this is why
>the cookbook pages I've posted all begin with "!!!Question" and
>"!!!Solution".  Whether this is appropriate, or whether it would work for
>unanswered questions is itself an open question.  :-)

Initially I viewed cookbook pages as pages where wizard-smart PHP-geeks 
posted their latest recipes so that mere mortals (like me) could download 
them and install them without needing to take PHP-101.

Having read many of the recipes (and put one up myself) I now view the 
cookbook as a bazaar where you can find all kinds of things - some of which 
you can use - some of which teach you about a topic - and some of which 
just question the mysteries of life without providing the answer.



Neil

Neil Herber
Corporate info at http://www.eton.ca/
Eton Systems, 15 Pinepoint Drive, Nepean, ON, Canada K2H 6B1
Tel: (613) 829-4668