Re: [GENERAL] Re: [HACKERS] [Fwd: SGVLLUG Oracle and Informix on Linux] - Mailing list pgsql-general

On Wed, 22 Jul 1998, James Olin Oden wrote:
> As far as documentation goes, I think that for the most part what is there is
> good.  Sometimes (and I realize I need to be more specific) it seems the very
> thing you are looking for you can't find; in the end that generally has been an
> issue of inexperience with SQL.

It seems to me that the documentation assumes some knowledge of SQL.
I don't know if this was intended or not, but if a new user DOESN'T
know anything about SQL, they are not going to learn it from the
PostgreSQL manuals. Here are some basic examples:

The small section in the User's Manual on the SELECT command is
extremely short and neither explains nor gives examples for the many
basic things you can do with SELECT. So, for instance, from the
documentation, a new user will learn that he can select whatever
fields he wants from a table and tell it to select only those
records (tuples) which meet an exact criteria (suchandsuch <
'soandso' AND blahblah = 'blah'). But let's say that he wants to
select NOT all records that contain only 'blah' in the blahblah
field, but rather, all records that have 'blah' ANYWHERE WITHIN the
blahblah field? No where in the PostgreSQL documentation (that I
could find) will he be told that he can do "blahblah LIKE '%blah%'".

So now let's say he doesn't want it to be case sensative. Nowhere
that I could find do the manuals tell him that he can do "blahblah
~* 'blah'". In fact, I didn't know that ~* even existed until
someone on the list suggested I do a "\do" in psql to get a list of
all the operators. Do you see how it seems like that information is
hidden down in an obscure help command in one program rather than
being right there in the User's Manual? What the User's Manual needs
is a nice long detailed description WITH A LOT OF EXAMPLES of the
SELECT command. Instead it seems to just mention it in passing.

Now the man pages suffer the same problem that the entire man page
system suffers: it pretends to be an online representation of a
printed set of manuals, but it is missing one major feature of
printed manuals: A TABLE OF CONTENTS! Some of the man page info IS
in the HTML docs, but I think EVERYTHING in the man pages should be
in the HTML manuals, (possible better organized than man pages
allow).

Most of the sections in the manuals are simply too brief. Consider
the section in the Tutorial on Redirecting SELECT Queries. It
explains the idea as quickly as possible, gives ONE example, and is
done. This doesn't help new users much.

I think you see my point. If I knew more about PostgreSQL and SQL in
general, I'd offer to write some, but I'm just in the learning
process now.

   Cheers.
 --Dan D.

-----------------------------------------------------------------------
 Daniel G. Delaney                    The Louisville Times Chorus
 Dionysos@Dionysia.org                   www.LouisvilleTimes.org
 www.Dionysia.org/~dionysos/          Dionysia Design
 ICQ Number: 8171285                     www.Dionysia.com/design/
-----------------------------------------------------------------------
                   I doubt, therefore I might be.