[pmwiki-users] Re: 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 03:52:02PM -0500, Waylan Limberg wrote:
> > On 12/30/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > > 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.
> > >     ...
> > 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.
>
> I think you're probably correct, that many people will simply assume
> that it's a link back to pmwiki.org and just go on from there.

There are always those "Initial Setup Tasks" and "Documentation Index"
links in the sidebar...

There's also a "PmWiki FAQ" link.  The FAQ page currently broken, btw.
 The first (:markup:) directive ends the >>faq<< division prematurely.

> But I'm wondering if it's also the case that by the time someone gets
> PmWiki installed and Main.HomePage running, they won't be looking at
> the README.txt/INSTALL.txt file any longer, or won't think to go back
> to it.

That's probably right, but that's OK.

Since those documents don't exist now, how can not looking at them
make someone any worse off than now?

> Unless the note about documentation availability occurs in README.txt
> (or INSTALL.txt) -before- the part about actually getting things to
> work, I think it's likely to never be seen.

I was thinking it would be noticeable in INSTALL.txt immediately after
the getting-things-to-work part.

DOCUMENTATION.txt is sounding better and better...

>  And even if it does
> occur before the install steps, it may be overlooked because it's not
> relevant to the admin's immediate task ("how do I install it?").

I think it should come before the install steps.  The original idea of
having a "Root README.txt With a docs/ Directory" was to shorten the
distance from unpacking the archive to having the wiki up and running.
 I think the docs/ directory is also a useful place to find
information about upgrading and customizing.

> I think it may be a bit of a cognition problem -- when an newbie
> admin first starts with PmWiki, they look at the README.txt file
> and INSTALL.txt files to answer the following questions
> (taken from Hagan's excellent posts):
>     * What does this program do?
>     * What are all these files and directories?
>     * How do I get started?
>
> But once PmWiki is installed, an admin is thinking "okay, I've
> started", and then have questions like
>     * Where is the documentation?

docs/DOCUMENTATION.txt?

>     * Okay, now how do I customize PmWiki?

docs/CUSTOMIZING.txt?

I think the existing wiki page documentation is coming along fairly
well, and that's where those questions are likely to be answered. 
There and on pmwiki.org.

> But by this time they may also think "I've already read the README.txt
> file", and so they discount looking there for more information.
> (This is why it's nice that sample-config.php is in the root, because
> it's the first place an admin will start to look for more information.)

README.txt will point them right to the file in docs/... or they'll
see docs/ and look there without even opening README.txt.

Hagan