Re: Documentation needs significant improvement - Mailing list pgsql-general

From Shridhar Daithankar
Subject Re: Documentation needs significant improvement
Date
Msg-id 200301251209.36274.shridhar_daithankar@persistent.co.in
Whole thread Raw
In response to Documentation needs significant improvement  (Chris Johnson <chris@chaska.com>)
List pgsql-general
On Saturday 25 January 2003 10:02 am, you wrote:
> I just wasted 20 minutes or so trying to re-figure out how the heck to
> create the first user.  Frankly, the documentation between the step of
> installing the binaries and the step of doing useful stuff with the
> database sucks.

Well, IMO, administrators guide is pretty nice. Just that if you try to do
anything before you finish reading it, chances that you will trip over
someplace.

In fact relooking at 7.3 admin guide, I would say that the order of chapters
is perfectl.

> * As far as I can tell, after reading 40+ sections, and searching up and
> down, it never even really tells you that you probably should create a
> database (e.g. "test") first and then use that database to bootstrap
> your user creation, or at least, that it MIGHT be safe to use a database
> called template1 (or 0) to do this, or that those 2 database are all
> that exist at this point, or even how to find out which databases, if
> any, exist.

Well, surely you haven't compeleted the manual reading, did you?

To quote from
http://candle.pha.pa.us/main/writings/pgsql/sgml/user-manag.html,
"Every database cluster contains a set of database users."

Then you can proceed to
http://candle.pha.pa.us/main/writings/pgsql/sgml/creating-cluster.html which
occure earlier than users page. So definition of cluster is already covered.

It is pretty clear that database users are in database cluster and can be
created even before database is created because template0 exists.

> Finally, after looking elsewhere than in the "official" docuemtation, I
> found a link to this site:  "PostgreSQL 101 by Shridhar Daithankar."  Lo
> and behold, Sridhar says create database "test" and go from there.
> Eureka.  Now I can get somewhere.

Glad that it helped you. But remember it is just one way to get things right.

> I'm not some clueless newbie who can be expected to stumble around for a
> while.  I'm an expert.

In general I agree with you that postgresql documentation is something that
should be read in one go. It is not that you can refer to a single page and
get done.

But in long term I find it an advantage. By the time you are set to do
something, either you know what to do or know where to find all relevent
stuff.

 Shridhar

pgsql-general by date:

Previous
From: Chris Johnson
Date:
Subject: Documentation needs significant improvement
Next
From: will trillich
Date:
Subject: hot to determine calculated fields (views)