Documentation needs significant improvement 
Author Message
 Documentation needs significant improvement

The new website look is nice.  It's a significant improvement over the
previous version, and it's much easier to find important things.  There
are some nits but they're not the main point of this message.

I installed PostgreSQL a couple months back on a FreeBSD system, and got
it working and started evaluating it for a large conversion from another
database effort.  Then other important projects came up, and I didn't
look at PostgreSQL for a couple months.  In the meantime, we got a new
development machine in-house.  Time to install PostgreSQL 7.3.1, the
latest and greatest, and continue the effort.

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.

* The arrangement and order of the primary documentation is not
conducive to getting this thing up and running.

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

* The web formatting of said documentation is hosed.  I'm guessing it's
a result of some conversion process from a former web layout.  Some
pages flow into resized windows just fine, as all good HTML documents
should.  Others have pre-formatted monospace-font lines with missing
line breaks resulting in ridiculously wide pages which have to be
scrolled horizontally -- which makes them near unusable.

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.

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

It should not be this hard, folks.



Wed, 13 Jul 2005 12:32:56 GMT
 Documentation needs significant improvement


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

Quote:
> * 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.

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

Quote:
> 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

---------------------------(end of broadcast)---------------------------
TIP 2: you can get off all lists at once with the unregister command



Wed, 13 Jul 2005 14:39:29 GMT
 Documentation needs significant improvement

Quote:

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

Criticism in the form of patches would be the most helpful ;-).
I hear your pain, but it's not clear to me exactly what to fix where.
For example:

Quote:
> * The web formatting of said documentation is hosed.  I'm guessing it's
> a result of some conversion process from a former web layout.  Some
> pages flow into resized windows just fine, as all good HTML documents
> should.  Others have pre-formatted monospace-font lines with missing
> line breaks resulting in ridiculously wide pages which have to be
> scrolled horizontally -- which makes them near unusable.

I use the HTML docs all the time, and it's been awhile since I saw any
pages that rendered that badly.  *Exactly which* pages are you
complaining about?  What browser are you looking at them with?

                        regards, tom lane

---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/users-lounge/docs/faq.html



Wed, 13 Jul 2005 14:45:05 GMT
 Documentation needs significant improvement

Quote:

> * The arrangement and order of the primary documentation is not
> conducive to getting this thing up and running.
[snip]
> 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.

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

> It should not be this hard, folks.

any chance you can help onjure a rough draft of what would have
helped you get up-to-speed? maybe we can help out the next guy
that way.

just a couple of paragraphs: "Chris's Quick-Start Guide to
PostGREsql v7.x.x". hmm?

--
There are 10 kinds of people:
ones that get binary, and ones that don't.


http://sourceforge.net/projects/newbiedoc -- we need your brain!
http://www.dontUthink.com/ -- your brain needs us!

Looking for a firewall? Do you think smoothwall sucks? You're
probably right... Try the folks at http://clarkconnect.org/ !

---------------------------(end of broadcast)---------------------------



Wed, 13 Jul 2005 14:55:50 GMT
 Documentation needs significant improvement

Quote:


> > * The web formatting of said documentation is hosed.  I'm guessing it's
> > a result of some conversion process from a former web layout.  Some
> > pages flow into resized windows just fine, as all good HTML documents
> > should.  Others have pre-formatted monospace-font lines with missing
> > line breaks resulting in ridiculously wide pages which have to be
> > scrolled horizontally -- which makes them near unusable.

> I use the HTML docs all the time, and it's been awhile since I saw any
> pages that rendered that badly.  *Exactly which* pages are you
> complaining about?  What browser are you looking at them with?

i think what he's referring to might be some of the
user-contributed techdocs. the body text is wrapped in <pre>
tags so linebreaks are hard-coded; a narrow window might lead to
awkward wrapping snafus. (depends on browser's behavior, of
course...)

for example, try my regex intro at
        http://techdocs.postgresql.org/guides/RegularExpressionIntro
and make your window narrow. it might look okay -- or not...

is there a way to revisit those and allow html formatting with
<h2> and <em> and such, and let the browser's text wrapping do
its thing?

:)

--
There are 10 kinds of people:
ones that get binary, and ones that don't.


http://sourceforge.net/projects/newbiedoc -- we need your brain!
http://www.dontUthink.com/ -- your brain needs us!

Looking for a firewall? Do you think smoothwall sucks? You're
probably right... Try the folks at http://clarkconnect.org/ !

---------------------------(end of broadcast)---------------------------



Wed, 13 Jul 2005 16:58:42 GMT
 Documentation needs significant improvement

Quote:
>any chance you can help onjure a rough draft of what would have
>helped you get up-to-speed? maybe we can help out the next guy
>that way.

>just a couple of paragraphs: "Chris's Quick-Start Guide to
>PostGREsql v7.x.x". hmm?

The detailed HTML docs are actually fine.

And there is a short version which works. But sets up what seems to be a
quick for test install with a superuser, no other users, and no startup and
shutdown scripts.

http://www.ca.postgresql.org/users-lounge/docs/7.3/postgres/installat...

So far that's much better than the Oracle doc I last saw- a huge thick
installation manual which is written for everyone and no one because it is
full of details for different scenarios. I had to turn to 3rd party Oracle
HOWTO to install Oracle- and it was a lot easier :).

Maybe people want an intermediate version?

 From memory my steps are usually:

Follow the INSTALL.TXT, configure, compile, regression test and if ok,
install the software.

Create a pgsql or postgres O/S user.

Set up the filesystem permissions and structure for the "database
cluster/instance".
do the initdb. Includes where you want the instance's logs to go.

Configure O/S to start postgresql instance on bootup (copy contrib scripts
over or write own using the pg_ctl stuff).

psql -U pgsql template1

alter user pgsql with password 'superuserpassword';
create user myuser with password 'blahblah' createdb;

\c - myuser
create database myuser;

edit pg_hba.conf to use passwords (note you may wish to use a different
authentication method).
restart postgresql instance.

Voila, postgresql up with one super user and one power user.

Note that most people won't want to follow my install because requiring
authentication breaks many Postgresql commandline utilities (not sure if
this is changed, since I haven't been using most of them - coz they didn't
work for me ;) ).

HTH,
Link.

---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate

message can get through to the mailing list cleanly



Wed, 13 Jul 2005 17:19:17 GMT
 Documentation needs significant improvement

Quote:

> The detailed HTML docs are actually fine.

Not to start a flame-fest, but really, just fine?  No room at all for
improvement?  Or very little room for improvement?  Let's take a
positive approach, instead of a defensive one.

Quote:
> And there is a short version which works. But sets up what seems to be a
> quick for test install with a superuser, no other users, and no startup and
> shutdown scripts.

> http://www.ca.postgresql.org/users-lounge/docs/7.3/postgres/installat...

That would have given me a few clues, although it still doesn't address
the prerequisites for user creation.  However, when I viewed it the
other day, ALL of the commands were on ONE long line without a break, so
  I would have to scroll horizontally for an eternity to find that
"createdb" command which provided the clue.

Today, I am unable to find the pages in all their horrible mess that I
read the other day.  My bet?  Someone or something hosed up a web page
install or upgrade or mirror site, and I *did* see garbage, but now it's
all gone.  I was not hallucinating.

Quote:
> So far that's much better than the Oracle doc I last saw- a huge thick
> installation manual which is written for everyone and no one because it is
> full of details for different scenarios. I had to turn to 3rd party Oracle
> HOWTO to install Oracle- and it was a lot easier :).

Oracle's documentation is incredibly obtuse.  I wouldn't want to strive
to be like them.

Quote:
> Maybe people want an intermediate version?

>  From memory my steps are usually:

> Follow the INSTALL.TXT, configure, compile, regression test and if ok,
> install the software.

> Create a pgsql or postgres O/S user.

        [snip]

Quote:
> Voila, postgresql up with one super user and one power user.

Good summary.  Note that some people (some being more than a few) will
be installing PostgreSQL on FreeBSD systems using the ports collection.
  The steps to get the source, build, test and install are handled by
one command:  "make install".  The only remaining steps are starting the
server and initializing the database, requiring exactly 2 more command
lines.

What I was looking for was the answer to the questions:  "I've got a
running instance of PostgreSQL.  I want to get administrative control of
the access (users) and create any initial databases (if necessary).  How
do I do that?  Which do I do first?"

It was non-obvious that the Unix username pgsql was the only
pre-existing superuser available, and that it had no default database,
but rather required use of template[01].  Or alternatively, through the
magic of opaque behavior, one can run createuser and it will magically
use template[01], or when trying to use createdb magically, one has to
know somehow that one must be the Unix user which owns the databases
(pgsql on FreeBSD).

I'll be more than happy to contribute better documentation.  However, I
looked in the "how to contribute" section and it only talked about
source code patches, so I was lead to believe that documentation was not
open to modification by the user community.



Sat, 16 Jul 2005 08:33:13 GMT
 Documentation needs significant improvement

Quote:


> > The detailed HTML docs are actually fine.

> Not to start a flame-fest, but really, just fine?  No room at all for
> improvement?  Or very little room for improvement?  Let's take a
> positive approach, instead of a defensive one.

Let's be reasonable here, there's a large difference between "actually
fine" to "No room at all for improvement" or even "very little room for
improvement".  I think that was unnecessary.

Quote:
> It was non-obvious that the Unix username pgsql was the only
> pre-existing superuser available, and that it had no default database,

I assume the text in the Administrator's Guide section 4.1 (using the
online dev docs) was not clear enough as for the existance and name of the
superuser.  The existance of a created superuser is  also mentioned in
context of the -U switch to initdb but not in the description.  Perhaps
it needs to stand out more.

Quote:
> but rather required use of template[01].  Or alternatively, through the

Well the existances of at least template1 is mentioned in a few places
(initdb, 3.2, 5.2) and mentioned in terms of bootstrapping creating
addtional databases in 5.2 but again maybe this isn't clear enough or
doesn't stand out enough.

Quote:
> magic of opaque behavior, one can run createuser and it will magically
> use template[01], or when trying to use createdb magically, one has to
> know somehow that one must be the Unix user which owns the databases
> (pgsql on FreeBSD).

At least the current doc srcs seem to mention in the man page source for
createdb that it's a wrapper over psql and AG 4.1 mentions that many
applications assume the name of the current operating system user by
default (including createuser and psql).

The docs are like most of the rest of the project, if you can work with
the document source files, you can probably get patches applied if you
make something better.

---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate

message can get through to the mailing list cleanly



Sat, 16 Jul 2005 09:35:59 GMT
 
 [ 8 post ] 

 Relevant Pages 

1. Documentation needs significant improvement

2. I-NewEra 2.11.WC1 any significant improvement?

3. Significant systems value improvement

4. Documentation improvement suggestions

5. documentation improvements

6. Paradox 7 improvements documentation.

7. documentation improvements

8. Documentation improvement suggestions

9. documentation improvements

10. documentation improvements

11. Performance improvement needed.

12. SQL Statement needs Performance Improvement


 
Powered by phpBB® Forum Software