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

[Ben Wilson]

Neil,

I think you have a good proposition. However, we may need a new group 
dedicated
to PmWiki-related FAQs: "PmFAQ." Thus, PmFAQ/PmFAQ would list all the topical
FAQ pages relevant to PmWiki.

PmFAQ/Groups
PmFAQ/Security
. . . etc . . .
PmFAQ/Spam
PmFAQ/InstallProblems

As a Community, we should be willing to take raw questions and convert 
them into
a more general question that may better server future users. I mean radical
revision as needs be.

We may also need to re-organize other pages. For example, some may not 
draw the
connection between WikiSpam and Security. So, moving Spam-related stuff from
the Security page nad putting it onto a Spam page (and then linking from
Security to Spam), may create a more-intuitive process for users.

I'm typically the one who has this said to him: not every user is a 
geek. :-) I
start speaking Geek and leave everybody else behind. So, as I say this, I
understand it is not an easy process.

Ben

Quoting Neil Herber <nospam at eton.ca>:

> 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 _______________________________________________
> pmwiki-users mailing list
> pmwiki-users at pmichaud.com
> http://host.pmichaud.com/mailman/listinfo/pmwiki-users
>



-- 
Regards,
Ben Wilson

"Mundus vult decipi, ergo decipiatur"