Re: Documentation needs significant improvement - Mailing list pgsql-general
From | Chris Johnson |
---|---|
Subject | Re: Documentation needs significant improvement |
Date | |
Msg-id | b14j45$27da$1@news.hub.org Whole thread Raw |
In response to | Re: Documentation needs significant improvement (Lincoln Yeoh <lyeoh@pop.jaring.my>) |
Responses |
Re: Documentation needs significant improvement
Re: Documentation needs significant improvement |
List | pgsql-general |
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.
pgsql-general by date: