[pmwiki-users] yet another documentation suggestion ...
nospam at eton.ca
Tue Aug 2 10:53:01 CDT 2005
Since I recently criticized the PmWiki FAQ page as not delivering what it
promised, I have been thinking about how to improve or replace it.
There really are many questions that pop up again and again in slightly
different forms on this list, so perhaps this list should be the guide to
what goes into a FAQ. Recent example: How do I restrict the creation of new
On PmWIki.org, a search for "restrict groups" does not find the page that
describes this activity. The string "limit groups" does find the page
The problem I usually have with a FAQ is trying to guess which question I
should ask to get the answer I need, and trying to find that one tiny
question in a forest of answers. The problem with a search is similar: What
terms should I search for?
Rather than having one mother-of-all-FAQs, I would suggest several FAQs
based on very broad categories such as:
- FAQs about Groups
- FAQs about Page Names
- FAQs about Links
Trying to decide what those categories should be is difficult, but I would
be inclined to start with very few, and add new ones as the existing FAQs
get too big, or the topics seem to stray too far from the title. These are
all value judgements, but hey! what's a wiki for if not collaborative
Following the principle of DRY, the FAQs should not repeat the info that is
already living on another doc page, rather, it should be an index and
disambiguator. By including synonyms in the Q, the FAQs should be
searchable. For the example above, the Q/A on the FAQs About Groups page
Q: How can I limit, constrain, restrict, or control the groups or group
names on my wiki?
A: There are several solutions
on http://www.pmwiki.org/wiki/Cookbook/LimitWikiGroups .
It could be argued that simply placing this Q at the start of the
referenced page would make it much more likely for a search to find the
page, but that only works well when there is a single page that answers the
Q. FAQ pages also offer the ability to scan the Qs, looking for something
that fits your general idea of what you want to ask.
Comments? Suggestions? Rebuttals?
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