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!).
Show quoted text
-----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