[pmwiki-users] 'User' documentation

[kjettil]

This post doesn't seem to have been distributed (exploder down ca 
07.30-10.00 GMT ?), so I resend it :

kjettil wrote:
> I very much agree with what Jayaram wrote yesterday (2006-03-15 22:41 
> in Re: [pmwiki-users] RFC: PITS 00701 -- WikiFarm confusion), and 
> would like to add some further aspects and a proposal.
>
> I'm a newbie to PmWiki. I made the first download only 13 days ago. 
> I've tested adaptation/modification of three downloaded skins, as well 
> as developed my own skin from scratch (using the pmwiki 
> documentation).  And I've set up three pmwiki sites [of which two 
> public are under beta testing with end users]. So, the documentation 
> is not at all that bad!
>
> But ... I've experienced various difficulties in finding useful 
> information for the 'end user' (and deleting not useful!).
>
> I see essentially three categories of 'users' of documentation.
>
> 1 - 'end user' - for which a lot is on a too complex level (for an 
> 'end user' who is supposed to be w/o any knowledge of html, etc). With 
> 'end user' I here mean a person who will contribute/author the texts.
> 2 - 'unexperienced administrator' - who is only interested in setting 
> up site(s) using one of the well tested skins. With 'unexperienced' I 
> mean someone almost w/o or with very little knowledge of html, css 
> (and php).
> 3 - 'experienced administrator' - who knows html, css and php and 
> intends to/needs to develop custom skins, markup, functions, etc.
>
> For the first category, the standard download download documentation 
> is already far too complex (and an overhead of too many kB!). As an 
> administrator you'll have to spend time taking out what's not needed 
> or not useful. (If you on top of that want to use the French 
> translations, you'll have to install almost 130 additional files, many 
> if not most of them containing information I find of hardly any 
> benefit to an end user!)
>
> For the second category, a lot more is useful, but it's still too much.
>
> For the third category, all seems to be useful and necessary, and the 
> combination with pmwiki.org seems to give answers to most of your 
> questions - provided you know where to find the answer! The search 
> facility is almost useless here. (I've had to create a separate page 
> on my local PC with shortcuts/links to useful information locations. 
> If I, when browsing the vast documentation, find something I believe 
> will be useful for me in the future and notice that the location is 
> not that obvious to find, I add a link to my shortcut list.)
>
> The above discussion leads me to conclude that there should be three 
> download packages. I'd propose something like this:
>
> 1 - an 'core' download pmwiki version - stripped to only include 
> wikilib.d information needed by the 'end user'. The sidebar, the 
> homepage and a couple of additional pages should be examples, to be 
> used as a starting point for a pmwiki site.
> 2 - an 'administrator' wikilib.d package - concentrating on the needs 
> of the 'unexperienced administrator'
> 3 - a 'developer' wikilib.d package - organized as a kind of developer 
> manual.
>
> Kjettil
>