[pmwiki-users] Re: Root README.txt With a docs/ Directory
DaveG
pmwiki at solidgone.com
Thu Dec 29 22:07:42 CST 2005
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
More information about the pmwiki-users
mailing list