A manual does not provide the same service that an FAQ
provides. The primary difference is the organization of the
information.
An FAQ is organized as a list of questions and
answers so that readers can find the question that they are
interested in.
A reference manual is organized by feature
or functionality so that readers can find the feature they want
to learn more about.
A user guide is organized by process (or use) so that readers can
find out how the software applies to the way they do their "work".
The above assumes that the information is the same. That may
be the case but in practical terms since the focus of each is different,
the information included isn't the same. For example, the FAQ would
probably give a simple or direct answer to the question and reference
"the CVS manual" for the complete answer or related topics.
To assume that one form of documentation will serve all types of
readers and their diverse needs is shortsighted. To assume that
one form is always more important than the other forms is
also shortsighted. To assume that someone would update one form
while leaving the other alone is yet again demonstrating lack of
foresight.
(For the dim-witted, of course you update the CVS manual if you
find something that isn't documented correctly. But no matter how
complete the CVS manual is, it will not eliminate FAQ's because it
isn't organized in a Q&A structure.)
By the way, please forget that I mentioned anything about maintaining
an FAQ. It's obvious that it wouldn't improve anything nor keep
"old-timers" from flaming newbies.
Goodbye,
Craig
----- Original Message -----
From: Greg A. Woods <[EMAIL PROTECTED]>
To: Craig Saunders <[EMAIL PROTECTED]>
Cc: <[EMAIL PROTECTED]>; Craig R. Saunders <[EMAIL PROTECTED]>
Sent: Friday, September 15, 2000 1:13 AM
Subject: why wast time to write a FAQ?
> [ On Thursday, September 14, 2000 at 17:55:20 (-0700), Craig Saunders
wrote: ]
> > Subject: Re: What is Cederqvist?
> >
> > If Greg thinks it would be a good idea and he (and others)
> > would be willing to forward their answers of FAQ's, I would
> > be willing to edit and compile the FAQ list, post it regularly and
> > keep it on a publicly accessible web site. (I would also scan
> > the mailing list for potential FAQ's and proactively update
> > the FAQ list. And, with a little reluctance, reconcile when old-timers
> > have different opinions on how to answer a question.)
>
> I would much much sooner see someone, anyone, take note of questions
> that frequently appear in this (and any other related) forum and to
> (re)write the manual sections that have thus far been inadequate in
> providing the information sought by those asking the questions
>
> Hopefully that person would be given have commit access to at least the
> documentation sub-directory of the shared repository once they've
> provided one or two such fixes to the manual.
>
> I'd suggest that this person take the time to query (offline) people who
> ask FAQs to find out directly why they didn't find the answer they were
> looking for in the manual. That way they can find out whether or not
> the person even looked in the manual in the first place.....
>
> IIRC it was Per Cederqvist who first decided that a FAQ was a bad form
> of information presentation in this context and though I originally was
> wary of losing the then gargantuan FAQ, I've since not missed it one
> little bit. There were at least several people far more worried about
> the disappearance of the FAQ at the time, but it's editor agreed with
> Per and given the massive effort that would have been required to
> continue to maintain the full FAQ nobody was willing to step up and take
> it on.
>
> Perhaps if the person editing the FAQ were also dedicated to updating
> the manual and keeping it relevant to user needs then I wouldn't argue
> against a general FAQ. However with very limited volunteer resources
> I'm quite certain that maintenance of an FAQ should be the lowest
> possible priority in the project.
>
> BTW, this is a generic issue that applies to any software package which
> has an active user forum such as info-cvs is.
>
> --
> Greg A. Woods
>
> +1 416 218-0098 VE3TCP <[EMAIL PROTECTED]> <robohack!woods>
> Planix, Inc. <[EMAIL PROTECTED]>; Secrets of the Weird <[EMAIL PROTECTED]>
>
>
