Toward better documentation

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?

Cheers,
D
--
David Fetter david(at)fetter(dot)org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778

Remember to vote!