Tobias Weingartner wrote:
>
> I'm going to agree with this wholeheartedly. *Most* of the FAQ's asked here
> are of the form "Why can't I, or How do I, do 'locking', etc". If those
> people had bothered to read the manual, they would have (with even half an
> IQ point) noticed that CVS advocates a copy-merge conflict resolution method,
> and we would not have had their questions in this forum in the first place.
>
And people are going to continue to ask these questions. We have the
choice of continuing to explain why copy-merge is a reasonable way
to go, or to have some sort of canned answer.
> To give an example of a project where a FAQ is not really "sanctioned", have
> a look at OpenBSD. Their man-pages have had sigificant work done to them.
Real documentation is good, although time-consuming (and I'm not
volunteering at this time).
> Most of the time when somebody asks a FAQ (yes, OpenBSD has a FAQ, but it is
> quite tiny in comparison to most other OS FAQ's out there) the usual response
> is one of 'man question(1)', where question refers to the man-page where the
> needed answer is documented.
>
I'm unfamiliar with the usual OpenBSD questions, but I would assume
that some questions are asked rather often and some less often. In
that case, it might make sense to have a FAQ on the order of:
Q. My system....
A. man fnord(3)
Unless the documentation is absolutely superb, and likely even then,
there are going to be tricky points that people miss, or overlook,
or get wrong in adapting the instructions to their system. These
tricky points can be gathered together into a FAQ, which can give
a quick answer and reference the manual.
> The FAQ in OpenBSD is used more to document errata and other things that
> should get fixed, and should already be fixed given an ideal world.
That's one use for a FAQ.
Q. My system...
A. Yup, that doesn't work yet. If you want to work on it....
> With time, people will recognize the manual as the authoratative piece of
> information (other that this list of course, :-) ) on CVS, and will consult
> it without us needing to use the cluestick every time somebody posts on
> this list...
>
Um, you have more faith in human nature than I do, Toby.
