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

[H. Fox]

On 12/30/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> On Fri, Dec 30, 2005 at 02:58:49PM -0700, H. Fox wrote:
> > 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/
>
> First, let's assume that there will be a docs/ directory in
> the distribution.
>
> I'm not entirely sure why we need to force the admin through the extra
> "proceed to docs/INSTALL.txt" step; unless INSTALL.txt is
> fairly lengthy I think it could easily be a section of README.txt.

FWIW, I originally distributed a monolithic README.txt with Qdig and
later switched to separate files and it has worked out pretty well. 
Qdig's INSTALL.txt has a table of contents like so:

    * Basic Instructions
    * Basic Instructions (with writable-tree and caption-edit setup)
    * Quick Setup Instructions (Drag, drop, [set up a directory,] browse)
    * Establishing The Writable Tree
    * Command Line Step-By-Step Instructions
    * Customizing Qdig
    * The Gallery Administration Script (admin.php)
    * Troubleshooting

http://cvs.sourceforge.net/viewcvs.py/*checkout*/qdig/qdig/INSTALL.txt?rev=1.20

Qdig's README.txt has a very short section that looks like this:

    INSTALLATION, LICENSE, and CHANGELOG
    ====================================

    See INSTALL.txt, LICENSE.txt, and CHANGELOG.txt

> In place of the lines that say "for installation advice, see
> docs/INSTALL.txt", just start a section with "== Installation =="
> and continue on from there.  The licensing information
> can then go in a "== Licensing ==" section below that.
>
> However, if the installation instructions seem like they'll be
> long, then INSTALL.txt is warranted.

I like the modular approach, with separate, purpose-specific files
having names that make their content self-evident.

One other (minor) reason to consider having a separate INSTALL.txt:
README.txt will be "servable" and documentation in docs/ will, in most
cases, not be retrievable over the web.

> In all of this, I'd also like to see a text file that describes
> how to do standalone installations of PmWiki (e.g., for installation
> on a local machine when a webserver isn't immediately available).

That's a good idea, especially if you want to draw attention to that capability.

> > > * 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.
>
> Yes, I was thinking the same thing -- just another pointer to the
> fact that the documentation is available locally after PmWiki is
> installed, as well as online.

With the modular approach (that is: separate, smaller files with
descriptive names), a quick perusal of docs/ will lead admins right
where they want to go.

Hagan