[pmwiki-users] yet another documentation suggestion ...

[H. Fox]

On 8/2/05, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> On Tue, Aug 02, 2005 at 08:51:22PM +0200, Joachim Durchholz wrote:
> > The traditional format is a single FAQ. Once it gets large, it gets
> > sectioned. If it gets unwieldy, it's split into files.
> 
> I prefer this -- a single FAQ until it gets too large, then start
> splitting.

One page is plenty.

To make scanning the questions easier, we could place them at the top
with intra-page links to the answers below.  Another way to break it
up: Table of Contents / topic headings.

Example with both (sort of):
http://www.mozilla.org/support/firefox/faq

That's what I think a well-made FAQ page looks/works like.  It answers
fifty questions and it's easy to use.

Importantly, it answers a few questions I hadn't thought of yet.

> > However, I don't think a PmWiki FAQ is really needed. Any topic that's
> > mentioned in the FAQ could just as well be made into a wiki topic.
> 
> Agreed.

I don't think FAQs and wiki topics are mutually exclusive.  Examples:

    Q: Why doesn't PmWiki use a database such as MySQL for page storage?
    A: See [[PmWiki.FlatFileAdvantages]].

    Q: How do I set up user-based passwords for my wiki?
    A: See [[Cookbook.AuthUser]] and [[Cookbook.UserAuth]].

A good FAQ page will give the reader an overview of things to watch
out for.  Pulling certain topics off the FAQ page will cause them to
be overlooked.

Hagan

p.s.: The CSS style of the FAQ page needs changing.  The "disappearing
Q: trick" is clever, but I think it's confusing.  It would be better
to just show the Q:.  That, or make the A: disappear too. The
bold/strong type is distracting -- OK, hideous.  Italics/emphasized
text might be better... or maybe just leave the font alone.