Re: Moving postgresql.conf tunables into 2003...

> > This sort of narrative belongs in the SGML docs, not in a CONF file.
> > In fact, one could argue that we should take *all* commentary out of
> > the CONF file in order to force people to read the docs.
>
> The SGML docs aren't in the DBA's face and are way out of the way for
> DBAs rolling out a new system or who are tuning the system.  SGML ==
> Developer, conf == DBA.
>
> > Database performance tuning will always be a "black art," as it
> > necessitates a broad knowledge of PostgreSQL, OS architecture, and
> > computer hardware.  So I doubt that we can post docs that would
> > allow any 10% time DBA to make PostgreSQL "fly", but hopefully over
> > the next year we can make enough knowledge public to allow anyone to
> > make PostgreSQL "sprint".
>
> I'm highly resistant to/disappointed in this attitude and firmly
> believe that there are well understood algorithms that DBAs use to
> diagnose and solve performance problems.  It's only a black art
> because it hasn't been documented.  Performance tuning isn't voodoo,
> it's adjusting constraints to align with the execution of applications
> and we know what the applications do, therefore the database can mold
> to the applications' needs.

I agree.

We often seem to forget simple lessons in human nature.  Expecting someone
to spend 20 extra seconds to do something is often too much.  In many cases,
the only "manual" that a person will see is the .conf files.

At the very least, if there is good documentation for these parameters,
maybe the conf file should provide a link to this info.

About the documentation...  The few times I've tried reading these sections
of the docs it was like reading a dictionary.

Bruce's book is a much better writing style because it starts out with a
basic concept and then expands on it, sometimes several times until a
thorough (but not exhaustive) example has been given.

The exhaustive material in the docs is good when you know what you're
looking for, and therefore is a critical piece of reference work.  I don't
want to belittle the authors of that material in any way.  An illustration
of this would be to compare the O'Reilly "... Nutshell" book series to
something like the [fictitious] book "Learn PostgreSQL in 24 hours".

To close this message, I would just like to add that one of the most
successful open source projects of all time could be used as an example.
The Apache httpd project is one of the few open source projects in wide
spread use that holds more market share than all competing products
combined.

It uses a three phase (if not more) documentation level.  The .conf file
contains detailed instructions in an easy to read and not-to-jargon-ish
structure.  The docs provide detailed tutorials and papers that expand on
configuration params in an easy to read format.  Both of these refer to the
thorough reference manual that breaks each possible option down into it's
nitty gritty details so that a user can get more information if they so
desire.

Matthew Nuzum        | Makers of "Elite Content Management System"
www.followers.net        | View samples of Elite CMS in action
matt@followers.net    | http://www.followers.net/portfolio/