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

[H. Fox]

On 12/29/05, christian.ridderstrom at gmail.com
<christian.ridderstrom at gmail.com> wrote:
> On Thu, 29 Dec 2005, H. Fox wrote:
>
> > On 12/29/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > > On Thu, Dec 29, 2005 at 03:06:18PM -0700, H. Fox wrote:
> > > >     This is the README.txt file for PmWiki, a wiki-based system for
> > > >     collaborative creation and maintenance of websites.  PmWiki is
> > > >     distributed with the following directories:
>
> Going off on a tangent here.... shouldn't we emphasize that there several
> ways to structure directories, e.g. for farm installations?

The idea is to keep it simple for first-time installers.  Less is more.

> > > I'm wonder if docs/INSTALL.txt will get to be out of date/sync with
> > > the wiki page version. (OTOH, the installation instructions haven't
> > > changed much over PmWiki's history, so perhaps this isn't an issue.)
> >
> > docs/INSTALL.txt should be a general enough so it doesn't need frequent
> > updating.  At the simplest level it could just refer to a page or two on
> > pmwiki.org.
>
> Do we even need it? Surely the most inept administrator should be able to
> follow something like the following from README:
>
>         For installation instructions, see
>                 http://pmwiki.org/wiki/InstallationInstructions

You mean  http://pmwiki.org/wiki/PmWiki/Installation ?

I think it's helpful to have self-contained instructions, even if
they're only minimal.

INSTALL.txt, like README.txt, should be short and to the point, maybe
with references to in-depth explanations (e.g. security implications)
and/or out-of-the ordinary subject matter (e.g. WikiFarms).

For example, the PmWiki.Installation page has a WikiFarms link at the
top, which I believe was put there by me when I refactored the page
prior to the release of PmWiki 2.0.    The docs can lead you to
information without flooding you with extraneous material.

Hagan