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

[Patrick R. Michaud]

On Fri, Dec 30, 2005 at 10:30:15PM +0000, Hans wrote:
> I am one of probably many rather lazy windows users and expect
> generally that software installs itself more or less painlessly and
> automatically. I am not in the habit of reading README files if I can
> see a setup.exe file, and I will consult help files later when needed,
> and only then, preferring to work things out myself on the fly and
> intuitively, if possible. I certainly would not look into a doc/
> directory for information about setting up software, nor to look for
> configuration file examples, which would need to be moved and
> modified.

This is very helpful, and I think it reminds us that we will need
multiple paths to get at the same information, to accommodate the
varying backgrounds of people coming to PmWiki.  Some people will
want to work from a list of steps to follow, while others will
do things "on the fly".

Here are my decisions -- these aren't absolutely set in stone, but 
they're the likely outcome unless someone has strong arguments to
the contrary:

* PmWiki will come with a short README.txt file in its base directory.

* COPYING will become docs/COPYING.txt .

* sample-config.php will move to the docs/ directory.

* We'll have a docs/INSTALL.txt file (Hagan says he will contribute
  a draft for this).

* The bulk of the documentation will remain as wiki pages in wikilib.d, 
  and not HTML files or text files generated from wiki pages.  We should
  put a note about it in INSTALL.txt, but we'll also create a short 
  docs/DOCUMENTATION.txt with a pointer to the local docs, as well
  as a note in the initial Main.HomePage.

* The README.txt and/or INSTALL.txt files need to have a pointer
  to information about running PmWiki in standalone mode without
  a webserver.  This can be via a link to Cookbook.Standalone, a 
  Standalone.txt file (this needs a better name), or both.

* We'll have a scripts/secure.php script that defaults to "secure"
  settings, with a note in docs/sample-config.php about how to
  include it.

* We'll include a sample-farmconfig.php in the docs/ directory.

Pm