Re: Documentation needs significant improvement

Lincoln Yeoh wrote:
> 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.

> 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/installation.html

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.

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

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

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