[Pmwiki-users] Documentation

Dave Noonan PmWiki
Wed Feb 18 15:23:55 CST 2004


Changed subject from "Re: [Pmwiki-users] Re: Re: Main.SideBar" as this 
is a different topic.

> Patrick R. Michaud wrote:
>
>I know, I've been writing a lot of documentation the past couple of days.  
>I think that Dave Noonan's comment about "documenting what *can* be 
>customized" is really at the heart of much of this, and I'm trying to 
>find a good structure in which to present/document it.  Perhaps it's 
>best done as a reorganization of the Cookbook, perhaps it's better 
>done as a tutorial, perhaps a combination of these and other things,
>but no matter what it's going to take some time to develop.
>  
>
    I'm thinking we (pmwiki-users) need to write some of the docs and 
you need to spend more time outdoors. :)  I'm amazed that at how quickly 
you respond to any query. 

    In that vein I'd be happy enough with a list of variables and maybe 
an explanation of their naming scheme. That should give us enough to at 
least write up brief (one line?) descriptions of them.  Very often all I 
really want to know is "which variable controls this" and "what was it's 
default value".  I wouldn't mind a single page that listed all the 
variables with one line descriptions.  The variable names might link to 
pages with additional discussion or advanced usage.

    Some guidelines on what we're looking for in documentation would be 
helpful too. I've updated a couple of pages recently but that's been 
largely with comments copied out of the scripts/*.  I'm not sure what 
ought to be included.  I frequently use the default value as a starting 
place so having that handy would be good.

    As for organization it bugs me that the documentation isn't it's own 
group (say, PmWikiDocs?).  I'm contstantly looking for it and then 
remembering it's in the PmWiki group. I can't see moving what's already 
there just for the sake of change. Maybe if we start a whole 
re-org/expansion of the docs? This would leave PmWiki as the rah 
rah/sales/introduction group.  Oooh... I'd be able to search 
PmWikiDocs/* and not get all the fluff!

    Speaking of fluff... Of the 168 pages in pmichaud.com/PmWiki quite a 
few are random things that people have thrown up there.  I don't care 
about that on my site but yours is the 'official' site. I wouldn't mind 
if it was in the playground (great idea, Christian) but it's in the 
middle of the 'official' documentation.  Maybe I'm just being a stick in 
the mud.

    Getting back on topic I think PmWiki has pretty good docs over all.  
I think we just need to work on getting info that comes out in 
pmwiki-users on the web page and maybe on a little more organization. 
-- 
Dave
-----------------------
Heroism on command, senseless violence, and all the loathsome nonsense 
that goes by the name of patriotism -- how passionately I hate them!
~ Albert Einstein



More information about the pmwiki-users mailing list