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

Neil Herber nospam at eton.ca
Tue Aug 2 15:08:15 CDT 2005


At 2005-08-02  08:51 PM +0200, Joachim Durchholz is rumored to have said:
>>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.
>
>Actually that's what a FAQ should be in the first place! The current FAQ 
>page is more a list of questions that one specific person asked, and hence 
>not of much worth.

This was more-or-less my point. The current FAQ is not a FAQ, and a good 
way to find the questions is to mine this list.


>>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 .
>
>Hmm... that's a different problem I think.
>Here's a suggestion: add a paragraph
>   Keywords: <the search that you entered and that didn't find this page>
>at the end of the page. That way, future searches that use these keywords 
>will find the page.

That is what I suggested at the end of the posting - that many keywords 
could be added to the target page. That still does not provide the 
browseability of a FAQ unless the search results display a summary or 
teaser text from each page. For example, the hits returned for PITS pages 
are completely useless for deciding upon their merit. The results from 
"limit groups" are:
PITS /
     00010
     00131
     00358
     00417

Only 00417 has anything to do with Groups (syncing them).

>>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
>
>The traditional format is a single FAQ. Once it gets large, it gets 
>sectioned. If it gets unwieldy, it's split into files.

I don't disagree. I was trying to anticipate more than a page worth of FAQs

>However, I don't think a PmWiki FAQ is really needed. Any topic that's 
>mentioned in the FAQ could just as well be made into a wiki topic.
>
>>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 .
>
>OK, make that
>
>   Keywords: constrain, restrict, control group names
>
>on the LimitWikiGroups page, and voilà! - it will be found.

I thought I persuasively argued that this could work *but* in a limited 
fashion when I said:
>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.


>To keep the keyword lists reasonable, I'd suggest adding just the first 
>verb that you used personally.
>
>Here's a suggestion for the Search Results page: a text to be displayed if 
>nothing appropriate was found (well, maybe this should be given always):
>
>"No topic found? Try some other keywords.
>NOTE: If you manage to find what you searched for, consider editing the 
>page and rewording it so that the words that didn't find that page are on 
>it, so people who use the same keywords in the future will find the page."

This strikes me as completely unworkable (or highly optimistic!). Entering 
a quoted phrase such as "limit groups" more often than not produces no 
hits. If after several tries I finally get something, do you seriously 
think that I will be in a frame of mind to add (or even remember) the 
phrases that did not work and enter them on the target page?

On the other hand, entering the two words "limit" and "groups" gives lots 
of hits that have nothing to do with what I am looking for - the search is 
too broad. Using something other than the default PmWiki search engine 
could give much better results, if you could specify the proximity of 
terms, for instance. I would rather stick with an all-PmWiki solution, and 
a FAQ or two would seem to be the easiest.

Warning: Possible ambiguity! In my original post, when I said I entered 
"restrict groups", I meant the two words but without the quotes.


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