[Pmwiki-users] Documentation--Commented local.php

Patrick R. Michaud pmichaud at sci.tamucc.edu
Fri Mar 7 15:39:46 CST 2003


> On Fri, Mar 07, 2003 at 02:47:43PM -0600, Louis Katz wrote:
> 
> There's sample-local.php in the scripts directory. Including a local.php
> with pmwiki would be wrong as upgrades could destroy their local
> customizations if they weren't too careful.
> 
> But it would probably be better to have most (all?) of the variables
> that PmWikiAdministrators are likely to want to change in
> sample-local.php with some documentation about how to use them and some
> example code to go along with it. All of which would be commented out,
> of course.

I think three key parts of the problem are having people (1) know to 
look for a file like sample-local.php, (2) know where to find it, and 
(3) know what to do with it when they do find it.  I don't have good
answers for these questions--the best I can come up with thus far is 
"read the PmWiki documentation".  However, this approach is greatly
at odds with my internal belief that the best documentation is self-
documentation; i.e., things ought to be where people first think to
look for them, which is frequently not the documentation.  Or, to
paraphrase Donald Norman ("The Design of Everyday Things"), signs
and labels (documentation) are generally band-aids to cover the
deficiencies of a poorly defined user interface.

Pm





More information about the pmwiki-users mailing list