On Wed, 30 Jan 2008 11:27:20 +0000
Gregory Stark <stark@enterprisedb.com> wrote:
> "Ow Mun Heng" <Ow.Mun.Heng@wdc.com> writes:
>
> > <rant>
> > One of the worst aspect of PG is the documentation, or the lack
> > of it in terms of "traditional" house. The Manual is fine and
> > all, but in most cases, what I find that it lacks is actually
> > examples. Either examples to show what it a particular
> > field/query means but also as a way to show exactly how a
> > particular problem can be solved.
>
> I always thought one of the best things about the manual was that
> it has tons of examples. Arguably too many examples for a reference
> manual but personally I find it easier to learn from examples than
> reference text anyways so I appreciate it.
Evil is in the details. Some examples don't really show off the power
of postgresql.
Sometimes you look at an example, you know other related stuff and
say... mmm I know I can push this further but how?
How/where is it possible to submit doc patches? Even for older
versions?
There were things I didn't find so easy to understand/guess in the
manual, no rocket science, I took note of them or I just found
external pages that actually explained how to do that and I think
their place should actually be in the manual.
BTW examples are a sort of specification too. I wouldn't
underestimate their more formal value. So I think they should be part
of *the* reference documentation with example output as well.
They shouldn't be of the kind "how-to" but of the kind "you can't
push the syntax further and this is what you'd expect as an output".
Many things are already there in the "VI Reference section" but some
are not, especially in the "V Server programming" part.
--
Ivan Sergio Borgonovo
http://www.webthatworks.it
