[pmwiki-users] suggestion for continuously improving PmWiki documentation
Neil Herber
nospam at mail.eton.ca
Fri Jan 28 14:22:08 CST 2005
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
More information about the pmwiki-users
mailing list