Thread: Re: Need for newbie friendly docs (was Newbie struggling...)
Geoff Caplan wrote: [I assume you meant this for the list, not just me] >With 7.1 Postgres has the potential to enter the mainstream and >compete with MySQL for popularity. But the framework of the docs was >laid at a time when I guess it was safe to assume that users would >have advanced *nix skills. > >I recently had to ask the list for help to set the $PGDATA variable. A >number of kind people responded with the answer. > >I had consulted the Postges and Great Bridge docs, the archive, >Bruce's book and three weighty volumes on *nix, and could not find a >word in any of them that explains how to do this. A single line in the >docs could have saved this user a couple of frustrating hours. I >suspect that this is a pretty typical newbie experience with Postgres >admin. > >Of course, this great list is an important resource. But until the >development team somehow finds the energy to review the docs and make >them more newbie friendly, I suspect that Postgres will remain a >platform for the gurus. This is a pity, because 7.1 really rocks and >deserves to be more widely used. > >Or perhaps we will have to wait for a killer newbie book like the Paul >DuBois book on MySQL - Bruce's book is helpful, but much too thin on >the admin issues. And because I suspect that Bruce was behind much of >the docs, it tends to share the same blind spots. > >Just the perspective of someone who is having to teach themselves >*nix/client-server the hard way. Your question about setting PGDATA was really about setting environmental variables in a shell; it is only incidental to PostgreSQL. There is an enormous amount of background knowledge assumed when you document an application, and this is necessary, or else every document would become a Windows-like spoon-feeder, which would spend so much time on basic stuff that it would never cover the real meat. I'm not sure that it is either possible or desirable for PostgreSQL to attempt to satisfy a newbie's need for basic training in Unix. -- Oliver Elphick Oliver.Elphick@lfix.co.uk Isle of Wight http://www.lfix.co.uk/oliver PGP: 1024R/32B8FAA1: 97 EA 1D 47 72 3F 28 47 6B 7E 39 CC 56 E4 C1 47 GPG: 1024D/3E1D0C1C: CA12 09E0 E8D5 8870 5839 932A 614D 4C34 3E1D 0C1C ======================================== "Submit yourselves therefore to God. Resist the devil, and he will flee from you." James 4:7
Oliver Elphick wrote:
<snip>
>
> I'm not sure that it is either possible or desirable for PostgreSQL to
> attempt to satisfy a newbie's need for basic training in Unix.
Yes. It is. Especially for fundamental, widespread technology like
PostgreSQL.
AT LEAST the community articles and additionally available documentation
should cater for mature people from many experience levels.
We can give guidance in newbie terminology for the basic concepts of
keeping their system operational long enough for them to get the hang of
it and go from there. i.e. a Kickstart guide.
Newbies have interesting ideas sometimes too. After all, they've spent
their time learning about something OTHER than Unix. :-)
Regards and best wishes,
Justin Clift
--
"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
- Indira Gandhi
Oliver Elphick > There is an enormous amount of background knowledge assumed when > you document an application, and this is necessary, or else every document > would become a Windows-like spoon-feeder, which would spend so much > time on basic stuff that it would never cover the real meat. > > I'm not sure that it is either possible or desirable for PostgreSQL to > attempt to satisfy a newbie's need for basic training in Unix. > Well, I have spent a lot of time writing instructional material, and I think it is a question of the right balance. You obviously have to assume the basics, like file management. An issue like the one I got stuck on, on the other hand, is not so basic (not covered in the thousands of pages of Unix documentation I consulted) and could have been explained with a single line example. In many ways it is a matter of mindset - when experienced people are writing it is difficult for them to visualise the roadblocks that will catch out those with less knowledge. More beginner friendly docs don't need to be much more verbose - it's about testing them and pinpointing the points of difficulty. The docs have room for many pages on how to do a SELECT, which is covered in detail in every SQL primer, so there is surely no reason why setup should not be covered a bit more clearly. Postgres is not so hard to use, but it is a bit of a pig to administer, and the docs are part of the problem. But I do understand that top quality docs require specific skills and resources which it is perhaps unreasonable to expect from an open source project. It will probably take a commercial effort from GreatBridge or a book to improve things. GreatBridge have made a start. I hope they continue to test and develop their docs, and don't regard the job as done... Geoff Caplan
On Fri, 27 Apr 2001, Justin Clift wrote: > Newbies have interesting ideas sometimes too. After all, they've spent > their time learning about something OTHER than Unix. :-) something... other... than... unix.... ? Justin, I'm not clear on what you mean. Can you give us an example? ;-) But really: sure! Oracle, ferinstance, realizes that many people run Unix *because* they want to run Oracle in a stable server environment. People may be making the same decision about PostgreSQL. We shouldn't have to write this, though... if people could contribute the great 'basics of Unix you need to know to be a decent DBA' stuff that's already on the web, we'd have plenty. -- Joel Burton <jburton@scw.org> Director of Information Systems, Support Center of Washington
Joel- In all fairness, there aren't any good HTML-based Unix tutorials. I've looked for them. In particular, Sun is worthless here, curious since their Java tutorial is (IMO) really well done. I'm hoping PostgreSQL is MORE stable than Oracle in our Solaris environment. The massive CPU/disk footprint of Oracle generates reliability errors in our databases which I hope can be avoided in a leaner package. This marvelous mailing list really gives me confidence. Clayton ----- Original Message ----- From: "Joel Burton" <jburton@scw.org> To: "Justin Clift" <justin@postgresql.org> Cc: "Oliver Elphick" <olly@lfix.co.uk>; "Geoff Caplan" <geoff@productivity.co.uk>; <pgsql-general@postgresql.org> Sent: Thursday, April 26, 2001 1:53 PM Subject: [GENERAL] Re: Re: Need for newbie friendly docs (was Newbie struggling...) > On Fri, 27 Apr 2001, Justin Clift wrote: > > > Newbies have interesting ideas sometimes too. After all, they've spent > > their time learning about something OTHER than Unix. :-) > > something... other... than... unix.... ? > > Justin, I'm not clear on what you mean. Can you give us an example? ;-) > > > But really: sure! Oracle, ferinstance, realizes that many people run Unix > *because* they want to run Oracle in a stable server environment. People > may be making the same decision about PostgreSQL. > > We shouldn't have to write this, though... if people could contribute the > great 'basics of Unix you need to know to be a decent DBA' stuff that's > already on the web, we'd have plenty. > > -- > Joel Burton <jburton@scw.org> > Director of Information Systems, Support Center of Washington > > > ---------------------------(end of broadcast)--------------------------- > TIP 6: Have you searched our list archives? > > http://www.postgresql.org/search.mpl >