[pmwiki-users] yet another documentation suggestion ...
H. Fox
haganfox at gmail.com
Tue Aug 2 17:03:56 CDT 2005
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.
More information about the pmwiki-users
mailing list