[pmwiki-users] Root README.txt With a docs/ Directory
haganfox at users.sourceforge.net
Sat Dec 31 04:02:10 CST 2005
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)
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.
More information about the pmwiki-users