Re: [DOCS] FAQ organization

Here is a general comments on maintaining the FAQ, and pointing people
to answers.

First, the FAQ is a pretty weird way to give people information.  It is
an almost random list of questions and answers.  If the list is long,
people can get very impatient, and start skimming over the list.  That
is OK, as long as they can find the information when they need it.
Unfortunately, because it is in random order, it makes things very hard
to find.

OK, my strategy.  Let me give you two examples.  People get deadlocks
quite often, usually novice SQL users.  We need to explain to them what
they have done so they can re-design their queries to avoid it.  I could
have put it in the FAQ, but it really belongs in the LOCK manual page.
So I put it in the lock manual page, and added a mention in the
'deadlock' error message to look at the 'lock' manual page for a
description of the problem.  This is perfect, because as soon as they
get the error, they are pointed to the proper place that has the exact
answer they need.  Same with the new postmaster -i option.  By putting a
mention in the libpq connect failure message to look for postmaster -i,
people are pointed right to the problem.

This has cut down on the problem reports tremendously.  I think
commercial software doesn't do very good in this area, probably because
the support people are not the same as the developers.  Because we are
the same people, we think of these things.

Second, if an FAQ issue is described in the manual pages or docs, I
point them to those, rather than re-iterating a long description of the
problem.  I have tried to move as much as possible OUT of the FAQ, and
into the well-structured manual pages or error message.  This leaves
real FAQ items on the FAQ, things that really don't fit in a manual page
or are too general to fit anywhere else.

I must say that people usually have been reading the FAQ, because we
rarely get a question that is answered on the FAQ.

--
Bruce Momjian                          |  830 Blythe Avenue
maillist@candle.pha.pa.us              |  Drexel Hill, Pennsylvania 19026
  +  If your life is a hard drive,     |  (610) 353-9879(w)
  +  Christ can be your backup.        |  (610) 853-3000(h)