Re: [DOCS] FAQ organization - Mailing list pgsql-hackers

On Sat, 18 Apr 1998, Bruce Momjian wrote:

> 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.

Well, this is why we need to structure it, so that it is _not_ a long
unsorted list of questions, and trying to group questions that look alike.

> 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.

Well, I understand what you want. Sure, the right solution for the FAQ
would be to give pointers to the manual pages. But sometimes it is not
sufficient. Sometimes, people have problems and have no idea where they
come from, they don't know where to look at, and what they should look at.
Sometimes there are more than one suitable way of solving a problem, since
similar problems can sometimes be best resolved by completely different
solutions, which are spread over the docs. There, the FAQ can be : "you've
got this kind of problems, you can solve it by doing that, or that, or
that. Look here, there, and there for details".

Sometimes, it's better not to wait for people to get the error messages.
As a software user, I often read quickly through the FAQs to look at
common errors people do, so that, even before I start using the software,
I have a vague idea of what I should not do. So, people dealing with
concurrent access/update have a chance to be said : "Beware! You should
look at the LOCK man page / `Concurrent access under Postgres' user manual
section if you feel you might have deadlock problems". Or to people using
JDBC, "don't forget to use the -i flag !", instead of waiting for them to
panic because it doesn't work the way it should.

> 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.

Well, actually, I've always found commercial software support docs - when
there are any - to be much worse that support files in free software :)
Especially the "troubleshooting" section, where they often consider 1. you
are dumb, and forgot to power on the computer 2. the software never fails,
so they don't describe at all the error code -3257.

> 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.

Well, the FAQ shouldn't re-say things in detail when they can be found
somewhere else. But sometimes, you have to explain the same things
differently because the problem doesn't direct people necessarily to the
right page, or maybe they should find it by themselves, but they don't,
because they are not familiar with the structure of the software or of the
support documentations.

Taking your example of the -i option : often people which have problems
concerning this don't even realize their problem comes from not allowing
the postmaster to listen to TCP/IP ports... they think JDBC, or perl
interface, or postgres itself, are not working, and the symptoms can be
quite different. You have to tell them the cause of their problem, and
where to look, and if you can provide a quick fix without obliging them to
dig in the docs, it can be only better.

Another example : constraints, foreign keys (I know the man pages will be
updated :) ). People ask questions like : "I did this which should work,
and it doesn't work in Postgres!". If they read the CREATE TABLE man page,
they would have the answer. But somehow there are people who, even after
reading the man page, won't see what's wrong. So the FAQ may be the
solution to their problem, saying quickly : "You cannot specify
constraints this way, do them that way (quick example). Read the CREATE
TABLE, CREATE INDEX man pages".

Hmm... actually, for this specific example, we could do a FAQ like this :

Qxx.xx : I tried to enter this SQL command as I used to in (MySQL,
Informix, ORACLE), and it doesn't work. Why ?

A : Every DBMS has some particularities in its SQL syntax. Please refer to
the Postgres man pages to see what syntax the Postgres parser follows.

etc...

and maybe some other questions, answering special cases where it is not so
evident... (we don't do subselects in target ?).

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

So by collecting questions on the mailing list, we can see what answers
the FAQ does not provide yet :)

Anyway, I think it's important for the FAQ to redirect people to the right
sections of the different manuals, but if you can have quick fixes, maybe
give them in the answer itself ("did you use the -i flag on the command
line ?").

It is better to say it twice, if it can help people solve their problem
faster, though answers _must_ stay short (or else they deserve to have a
special section in the main docs and a pointer to it :) ).

Do I seem reasonable ??

Patrice

--
Patrice HÉDÉ --------------------------------- patrice@idf.net -----