From: | "Marc G(dot) Fournier" <scrappy(at)postgresql(dot)org> |
---|---|
To: | David Fetter <david(at)fetter(dot)org> |
Cc: | PG Hackers <pgsql-hackers(at)postgresql(dot)org> |
Subject: | Re: Toward better documentation |
Date: | 2004-07-18 20:12:42 |
Message-ID: | 20040718170929.R794@ganymede.hub.org |
Views: | Raw Message | Whole Thread | Download mbox | Resend email |
Thread: | |
Lists: | pgsql-hackers |
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(at)hub(dot)org Yahoo!: yscrappy ICQ: 7615664
From | Date | Subject | |
---|---|---|---|
Next Message | Peter Eisentraut | 2004-07-18 20:14:23 | Re: Toward better documentation |
Previous Message | David Fetter | 2004-07-18 19:51:26 | Toward better documentation |