[pmwiki-users] Re: Root README.txt With a docs/ Directory
H. Fox
haganfox at users.sourceforge.net
Sat Dec 31 03:54:09 CST 2005
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
More information about the pmwiki-users
mailing list