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

Good points.  The only comment I have is that the FAQ does now point to
several SQL tuturials on the web, and the psql \d commands are mentioned
as ways to find information about the system.  We don't list them in the
manual because they are always changing, because we are a
user-extensible system.  Every release has new types, so we just tell
people to use the \d commands.  I just improved them for 6.4 so the
output is clearer.

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