[pmwiki-users] yet another documentation suggestion ...

[Neil Herber]

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 
groups?

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 
http://www.pmwiki.org/wiki/Cookbook/LimitWikiGroups .

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 
authoring?

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 
might be:

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?


Neil

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