Thread: RE: Re: Need for newbie friendly docs (was Newbie strug gling...)

I think that Geoff has a point.
The section in the docs on setting environment variable is thin, to say the
least.
References to other relevant environment variables are scattered here and
there throughout the docs.  I have never been able to find a single
reference which covers which environment variables matter for PostgreSQL,
and why.
I feel Geoff's pain, having felt plenty already for similar reasons (still
do).  I had to blindly stumble across the fact that the PGDATA and PGLIB
variables, for example, were useful things to set.
If we are trying to resist documentation bloat, then maybe the
non-documentation documentation can address this subject?  Justin, if you
are reading, perhaps you can cajole someone to write a piece for the
techdocs site?(I'm not volunteering: I need to read it myself!).

> -----Original Message-----
> From:    Oliver Elphick [SMTP:olly@lfix.co.uk]
> Sent:    Thursday, April 26, 2001 6:30 AM
> To:    Geoff Caplan
> Cc:    pgsql-general@postgresql.org
> Subject:    [GENERAL] Re: Need for newbie friendly docs (was Newbie
> struggling...)
>
> Geoff Caplan wrote:
> [I assume you meant this for the list, not just me]
>   >With 7.1 Postgres has the potential to enter the mainstream and
>   >compete with MySQL for popularity. But the framework of the docs was
>   >laid at a time when I guess it was safe to assume that users would
>   >have advanced *nix skills.
>   >
>   >I recently had to ask the list for help to set the $PGDATA variable. A
>   >number of kind people responded with the answer.
>   >
>   >I had consulted the Postges and Great Bridge docs, the archive,
>   >Bruce's book and three weighty volumes on *nix, and could not find a
>   >word in any of them that explains how to do this. A single line in the
>   >docs could have saved this user a couple of frustrating hours. I
>   >suspect that this is a pretty typical newbie experience with Postgres
>   >admin.
>   >
>   >Of course, this great list is an important resource. But until the
>   >development team somehow finds the energy to review the docs and make
>   >them more newbie friendly, I suspect that Postgres will remain a
>   >platform for the gurus. This is a pity, because 7.1 really rocks and
>   >deserves to be more widely used.
>   >
>   >Or perhaps we will have to wait for a killer newbie book like the Paul
>   >DuBois book on MySQL - Bruce's book is helpful, but much too thin on
>   >the admin issues. And because I suspect that Bruce was behind much of
>   >the docs, it tends to share the same blind spots.
>   >
>   >Just the perspective of someone who is having to teach themselves
>   >*nix/client-server the hard way.
>
> Your question about setting PGDATA was really about setting environmental
> variables in a shell; it is only incidental to PostgreSQL.  There is an
> enormous amount of background knowledge assumed when you document an
> application, and this is necessary, or else every document would
> become a Windows-like spoon-feeder, which would spend so much time on
> basic stuff that it would never cover the real meat.
>
> I'm not sure that it is either possible or desirable for PostgreSQL to
> attempt to satisfy a newbie's need for basic training in Unix.
>
> --
> Oliver Elphick                                Oliver.Elphick@lfix.co.uk
> Isle of Wight                              http://www.lfix.co.uk/oliver
> PGP: 1024R/32B8FAA1: 97 EA 1D 47 72 3F 28 47  6B 7E 39 CC 56 E4 C1 47
> GPG: 1024D/3E1D0C1C: CA12 09E0 E8D5 8870 5839  932A 614D 4C34 3E1D 0C1C
>                  ========================================
>      "Submit yourselves therefore to God. Resist the devil,
>       and he will flee from you."          James 4:7
>
>
>
> ---------------------------(end of broadcast)---------------------------
> TIP 3: if posting/reading through Usenet, please send an appropriate
> subscribe-nomail command to majordomo@postgresql.org so that your
> message can get through to the mailing list cleanly

Hi all,

Some people have separately volunteered to write parts of a newbie's
guide to PostgreSQL in the last week or so, so there's a good chance
something will pop up in the next ummm... hopefully week or two.

Might not be huge pieces of work at the moment, but like everything,
something is better than nothing, and can be improved.  :-)

Has everyone noticed Vince's test of searchable PostgreSQL documentation
at :

http://odbc.postgresql.org/docs/ ?

Like, you type in your search words, and it brings up a list of pages
mentioning those words.  Plus the links to view the document.

And you can add comments.

It's based on the 7.1 document collection, and he's developing it
presently.  It's still Really useful now too though.

:->

Regards and best wishes,

Justin Clift

Jeff Eckermann wrote:
>
<snip>
> I think that Geoff has a point.
> The section in the docs on setting environment variable is thin, to say the
> least.
> References to other relevant environment variables are scattered here and
> there throughout the docs.  I have never been able to find a single
> reference which covers which environment variables matter for PostgreSQL,
> and why.
> I feel Geoff's pain, having felt plenty already for similar reasons (still
> do).  I had to blindly stumble across the fact that the PGDATA and PGLIB
> variables, for example, were useful things to set.
> If we are trying to resist documentation bloat, then maybe the
> non-documentation documentation can address this subject?  Justin, if you
> are reading, perhaps you can cajole someone to write a piece for the
> techdocs site?(I'm not volunteering: I need to read it myself!).


--
"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
     - Indira Gandhi