Re: Documentation needs significant improvement
От | will trillich |
---|---|
Тема | Re: Documentation needs significant improvement |
Дата | |
Msg-id | 20030130173640.GB3237@mail.serensoft.com обсуждение исходный текст |
Ответ на | Re: Documentation needs significant improvement (Chris Johnson <chris@chaska.com>) |
Ответы |
Re: Documentation needs significant improvement
("Ron St.Pierre" <rstpierre@syscor.com>)
Re: Documentation needs significant improvement ("Shridhar Daithankar<shridhar_daithankar@persistent.co.in>" <shridhar_daithankar@persistent.co.in>) |
Список | 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@serensoft.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/ !
В списке pgsql-general по дате отправления: