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

[DaveG]

H. Fox wrote:
> 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'll weigh in as a relative newcommer. It is *very* helpful to have a 
basic install.txt file -- even now after a few upgrades I have to do a 
quick think before I move forward. Upgrading/installing is a simple 
process, so keep the install.txt simple as well.

> 
> 
>>>>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.
I agree. A link for further reference may not hurt, but that tends to 
prompt the reader to thinking there's more info they are missing out on :)

> 
> 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.
Farms install's I'd either put in a separate TXT or provide a link to 
the info on-line.

  ~ ~ Dave