The FAQ (was Re: Creating an Admin Handbook)

[Murray Stokely]

On Tue, Jul 20, 2004 at 04:07:59PM +0200, Marc Fonvieille wrote:
> Why FAQ is not really used/read?  It's difficult to answer to that
> question but I assume cause it's less "famous" and cause the human being
> is lazy, it's an effort to go read the Handbook, so switching to the FAQ
> is too much :) and since the FAQ is not linked (and not detailled) from
> the Handbook, people ignore it.  It's not wrong to tell that a lot of
> people ignore the FAQ exists. (I know there is an old project to
> link/merge the FAQ in a dynamic way with the Handbook)
> The more you split a document the more you will fell in a such
> situation.

I don't think it's a fair comparison since the FAQ is written in a
much less formal style than the rest of our documentation.  It is also
HUGE for a 'FAQ' and people just aren't used to wading through such a
huge list of boring error messages that don't apply to them, and
information about pieces of hardware they've never heard of before
they get to something that is relevant for them.

The FAQ to me just doesn't work well as a static document.  I think
the FAQ should be the backend for a DocBook aware knowledgebase search
tool.  Until that time we can at least take comfort in knowing that it
is searched with www.freebsd.org/search, although the engine returns
an entire HTML page rather than just the relevant DocBook <answer>
elements as would be ideal.

Whenever anything is added to the FAQ that is easy to read, broadly
relevant, and well written, (i.e., something you would want to link
to), we scoop it up and add it to the Handbook.  I don't think that is
a bad thing.  The FAQ is great for questions about specific hardware
models and such, and I like to think that it still does a service to
people who find that content through our search engine (or through
google).

  - Murray