Re: Documentation needs significant improvement

On Mon, 27 Jan 2003, Chris Johnson wrote:

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

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.

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

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

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