Documentation needs significant improvement

Chris Johnson <chris@chaska.com>

From: Chris Johnson <chris@chaska.com>
To: pgsql-general@postgresql.org
Date: 2003-01-25T04:32:56Z
Lists: pgsql-general
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.