Re: Documentation needs significant improvement

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