From: | will trillich <will(at)serensoft(dot)com> |
---|---|
To: | pgsql-general(at)postgresql(dot)org |
Subject: | Re: Documentation needs significant improvement |
Date: | 2003-01-30 17:36:40 |
Message-ID: | 20030130173640.GB3237@mail.serensoft.com |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-general |
On Mon, Jan 27, 2003 at 06:33:13PM -0600, 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.
from your perspective (and mine) you're right. not knowing WHAT
to look for or WHERE to look for it, makes the existing docs
obtuse, obscure and non-helpful. once you know, sure, you can
find it easily -- but there's a threshold there. plus, you
already know it, so why look?
from the perspective of the folks who worked on making the
documentation as good as it is, you're being a tad petulant.
"don't be defensive" and all that.
don't take it personally; the docwriters aren't TRYING to make
your life difficult [it just works out that way :) ]...
the problem is, the folks who grok every nook and cranny of the
pgsql engine ALREADY know everything about it and are in a bad
position when it comes to introducing it to newbies; THEY know
it, so it's reasonable that YOU should be able to see it the way
they do. this is why i started the newbiedoc project for newbies
coming into debian -- documents written BY newbies FOR newbies
tend to be much more meaningful when you're entering the on-ramp.
> 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).
we await your improved documentation. :)
> 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.
the "idocs" portion of the website allows all kinds of
commentary, but that's basically footnotes appended to the
bottom of the page, forum-style. so that doesn't count--
i wrote an intro to regular-expressions, postgresql style, at
http://techdocs.postgresql.org/guides/RegularExpressionIntro ;
have a look -- and notice the "edit this page" link at the top.
piece of cake! i first submitted it right here on the mailing
list; after a few feedback cycles -- notably r. schwartz
(rightly) pointing out my email pattern was substandard -- it
wound up on the website. nothing to it!
--
There are 10 kinds of people:
ones that get binary, and ones that don't.
will(at)serensoft(dot)com
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/ !
From | Date | Subject | |
---|---|---|---|
Next Message | Josh Berkus | 2003-01-30 17:56:56 | Re: One large v. many small |
Previous Message | Noah Silverman | 2003-01-30 17:34:36 | One large v. many small |