Re: Toward better documentation

David Fetter wrote:

>Kind people,
>
>It's been pointed out to me that I tend to document by example
><http://fetter.org/sgml/plperl.html>, e.g.
>
>My personal opinion is that this is a good thing, and should happen
>throughout the PostgreSQL documentation. However, this is not my
>decision to make.
>
>Here's some pros & cons, as I see it, for including more examples in
>standard docs.
>
>Pros:
>* Accomodates different learning styles
>* Jump-starts development by providing working code
>* Built-in tests for breakage of backward compatibility
>
>Cons:
>* Start-up costs re: actually writing & checking the examples
>* Bigger document base to update & maintain
>* Disk space
>
>What do you all think?
>
>
>
>

I doubt you will find any objections to more examples. However I am sure
there would be many objections to substituting examples for reference
material. Rather, examples should illustrate and amplify the reference
material.

Also, there does need to be a consistent style in the docs. I suggest
one reasonable guideline, given the primary function of the docs as an
authoritative reference, and following the style mainly used already, is
'reference material first, examples following' in each relevant section.

If we were preparing docs intended primarily as teaching material, very
different principles might apply, but personally I don't see that as the
primary purpose of the docs.

cheers

andrew