[pmwiki-users] Root README.txt With a docs/ Directory

[H. Fox]

On 12/30/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> * I don't know if we need a separate INSTALL.txt or if this should
>   just be part of the README.txt file.  If we create a separate
>   "docs/" directory to hold text files, then we can place an INSTALL.txt
>   there, otherwise I think we just make it part of README.txt to
>   reduce clutter in the base directory.

I'll draft a docs/INSTALL.txt when I get the chance, since I'm the one
who thinks it would be useful.

The purpose of that file is to "soften the landing" for someone
installing for the first time or perhaps just considering doing so. 
It also allows PmWiki to be installed on a non-connected machine.

I'm imagining some easy steps to PmWiki new-installation bliss:

    Unpack archive.
    Read README.txt
    Proceed to docs/INSTALL.txt
    Install
    Configure, using online docs and samples in docs/

> * We'll continue to have a sample-config.php file, but it's not
>   clear where this file belongs.  Currently it's in the base directory,
>   which means it's quickly spotted by newbie admins (a good thing),
>   but adds more overhead to the base directory.  The sample-config.php
>   could go into local/, where it's little less likely to be seen
>   (how much less likely?) but more likely that the admin will then
>   properly put config.php in its desired location.  It could also
>   go into a docs/ directory, but I'm not entirely sure it's really
>   "documentation".

It's not a manual per se, but it's documentation to the extent that it
explains and provides some configuration settings.  Personally I just
cut and paste from it nowadays.

With a docs/ directory, the decision of what to include in
sample-config.php and what to leave out would be made much easier. 
Other sample configuration files -- or maybe a CONFIGURATION.txt file
-- could be created for cut-and-paste convenience.

> * One possible point of confusion with having a "docs/" directory
>   is that a quick file perusal might seem to indicate that PmWiki
>   doesn't come with a lot of documentation (since the bulk of the
>   documentation is really being stored as wiki pages in wikilib.d/).

If that's really a problem (I'm not yet convinced it is), there could
be a helpful docs/DOCUMENTATION.txt file containing all of the
pertinent details.

> * I think we may need a sample-farmconfig.php somewhere, probably
>   in the same location as sample-config.php.  This probably argues
>   against keeping sample-config.php in the base directory -- i.e.,
>   they should go in either local/ or docs/ .

I like the idea of keeping only local files (aside from .htaccess) in local/ .

Hagan