Documentation needs significant improvement 
Author Message
 Documentation needs significant improvement

Quote:


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

Quote:
> 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. :)

Quote:
> 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://www.***.com/ ;
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.


http://www.***.com/ !
http://www.***.com/ !

Looking for a firewall? Do you think smoothwall sucks? You're
probably right... Try the folks at http://www.***.com/ !

---------------------------(end of broadcast)---------------------------
TIP 6: Have you searched our list archives?

http://www.***.com/



Tue, 19 Jul 2005 01:36:58 GMT
 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.

Quote:



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



Tue, 19 Jul 2005 01:59:17 GMT
 Documentation needs significant improvement
On Thu, Jan 30, 2003 at 17:59:17 +0000,

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

Another good step is too read through the entire documentation once.
It will give you a good idea of what is there and where abouts it
might be located. So when a question comes up you have some idea
where to look.

---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate

message can get through to the mailing list cleanly



Tue, 19 Jul 2005 07:19:55 GMT
 Documentation needs significant improvement

Quote:


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

OK. (Sorry I am replying to a reply but lost original one.)

Quote:
> > 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?"

Well, I hope you have read postgresql 101, I have written. Who is postgresq=
l=20
superuser? Any OS user that starts the postmaster process. It is as simple =
as=20
that. Why you need a pre-defined postgreql superuser? Is pg_ctl too hard fo=
r=20
you?

So you have a running instance of postgresql. Who is postgresql superuser. =
The=20
userid with which postmaster is running. Is it that difficult to understand?

Quote:
> > 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).

That has nothing to do with postgresql. It can run with any user as superus=
er.=20
OS users postgresql and pgsql are packaging wrappers created by OS packager=
s=20
like freeBSD and distros. You are all too free to run a instance by yoursel=
f.

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

Join the postgresql-doc mailing list. You will find more than enough ways t=
o=20
contribute.

 Nothing is wrong with anything, either you or postgresql documentation. It=
's=20
just that the documentation assumes some knowledge of OS administration.=20
Probably they should mention it ..;-)

 Shridhar

---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/users-lounge/docs/faq.html



Tue, 19 Jul 2005 14:37:27 GMT
 
 [ 4 post ] 

 Relevant Pages 

1. Documentation needs significant improvement

2. Significant systems value improvement

3. I-NewEra 2.11.WC1 any significant improvement?

4. documentation improvements

5. Documentation improvement suggestions

6. documentation improvements

7. documentation improvements

8. documentation improvements

9. Paradox 7 improvements documentation.

10. Documentation improvement suggestions

11. SQL Statement needs Performance Improvement

12. Performance improvement needed.


 
Powered by phpBB® Forum Software