Re: Toward better documentation

On Sun, 18 Jul 2004, 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?

Agreed, where applicable ... *but* ... there is nothing stopping anyone 
from submitting patches for such examples, is there?

----
Marc G. Fournier           Hub.Org Networking Services (http://www.hub.org)
Email: scrappy@hub.org           Yahoo!: yscrappy              ICQ: 7615664