Re: Need for newbie friendly docs (was Newbie struggling...)

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