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

[Waylan Limberg]

On 12/30/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> On Fri, Dec 30, 2005 at 12:25:08PM -0500, Waylan Limberg wrote:
> > On 12/30/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > > On Fri, Dec 30, 2005 at 10:56:47AM +0000, Hans wrote:
> > > > Comment:
> > > > I hope it will be not necessary to create a docs/ directory, and
> > > > keep just the minimal text information in the root, as at present.
> > > > The main documentation exists in form of wiki pages within wikilib.d,
> > > > which the above does not make clear. So perhaps it can read:
> > > > wikilib.d/      Default wiki pages including main documentation
> > >
> > > I agree, we should make it clear that the main documentation is
> > > in wiki pages.
> >
> > That wasn't clear to me at first. I was working on a unconnected
> > machine, and after spending a few weeks going back and forth between
> > two machines checking the docs at pmwiki.org and making adjustments, I
> > finally realized everything was right there. Pointing that out in a
> > README file would have clued me in much quicker, as that would have
> > been the first thing I looked at after unpacking the download.
>
> After thinking about this a little bit more, I'm actually a little
> surprised.  As soon as the PmWiki software is installed, the first
> thing that appears on Main.HomePage is:
>
>     Here are some useful default pages installed along with the
>     PmWiki software:
>
>     * PmWiki documentation is available at PmWiki.DocumentationIndex.
>     ...
>

I admit that I should have caught on sooner than I did. While I don't
recall exactly what my thinking was on that, I'm inclined to say that
I assumed it was a link to the content on pmwiki.org, not a local copy
- so I never even clicked it. Seeing that most other projects I have
tried over the years do this, it seems like a reasonable assumtion to
me.

Then I made some changes and never looked at the original content of
Main.HomePage again.

> So, what exactly does the README.txt file need to say about
> the local availability of the documentation, and where does
> it need to be said?
>

Perhaps something like:
The documentation is available on this local installation at
http://yourdoman/PmWiki.DocumentationIndex or on the web at
http://pmwiki.org...

I'm sure someone else could come up with better wording. But that
should have been enough.

> > It would have made more sense to me it
> > put the sample either in the local dir, or in some dir that it would
> > obviosly need to be moved from (like sample/ etc.).
>
> Noted.  Out of curiosity, how long do you think it would've taken
> you to find the sample-config.php file in local/ instead of the root?

Good question! I have no idea. However, with the clear instructions in
the proposed README, I would have more likely seen it. Of course, as
you pointed out, I missed the comments in the sample, but then again I
never do read comments real close unless I run into problems (or I'm
trying to figure out a section of code). Seeing config.php worked in
the root dir, I didn't give it a second thought untill I looked at
securing everything (which isn't really an issue when considering the
first line of the file).

I guess my point is that while you have a good point why
sample-config.php should be in the root dir, that argument does not
hold up IMHO with a clearly written README in the root dir.
--
----
Waylan Limberg
waylan at gmail.com