Re: Documentation needs significant improvement

A little while ago I was a db newbie and a complete postgres newbie, so
I'll add my two cents worth. The current documentation is really quite
good, however the problem I had was trying to find what I needed in
them. Two things helped quite a bit:
1 - a good reference book eg PostgreSQL Essential Reference (but not
Practical PostgreSQL - the index is VERY sparse)
2 - pgAdminII - The searching mechanism in the help files is AWESOME.
It's a very quick and easy tool to use, and it's current (my version is
7.3 rc1). If you have a windows box available, I urge you to try pgAdmin
II, even for the documentation alone.

So, if someone created a web interface that did the same as pgAdminII
(its Help contents), it would solve most of the problems of finding what
a user needs in the documentation (in my humble opinion).

BTW Will, your regular expression docs are very good, they've been quite
helpful to me over the last couple of days.

will trillich wrote:

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

--
Ron St.Pierre
Syscor R&D
tel: 250-361-1681
email: rstpierre(at)syscor(dot)com