[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