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

[Patrick R. Michaud]

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.

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.  (You didn't answer the question about *where* the
statement should go in README.txt.  :-)

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.  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 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?
    * Okay, now how do I customize PmWiki?
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.)

Maybe the solution is to fix the default Main.HomePage, so that it 
reads something like:

    Welcome to PmWiki!

    '''First time installers:'''  A local copy of PmWiki's
    documentation has been installed along with the software,
    and is available via the [[documentation index]].  To
    continue setting up PmWiki, see [[initial setup tasks]].

    The [[basic editing]] page describes how to create pages
    in PmWiki, and you can practice editing in the [[wiki sandbox]].

This way the first thing that a newbie admin encounters once
PmWiki is running is a highlighted note that clearly calls out
to people doing their first installation, and directs them
where to go next.

The InitialSetupTasks page can then have another note at the top 
reminding new admins that a copy of the documentation is 
available locally, and it can be accessed via the DocumentationIndex.

Does this sound workable/better?

Pm