[HACKERS] Toward better documentation

2004-07-18 Thread David Fetter
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

Re: [HACKERS] Toward better documentation

2004-07-18 Thread Marc G. Fournier
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

Re: [HACKERS] Toward better documentation

2004-07-18 Thread Peter Eisentraut
David Fetter wrote: It's been pointed out to me that I tend to document by example Documenting by example is like proving by example -- it helps understanding, but it doesn't replace the actual thing. Nonetheless, no one ever claimed that more examples would be a bad thing. -- Peter

Re: [HACKERS] Toward better documentation

2004-07-18 Thread David Fetter
On Sun, Jul 18, 2004 at 10:14:23PM +0200, Peter Eisentraut wrote: David Fetter wrote: It's been pointed out to me that I tend to document by example Documenting by example is like proving by example -- it helps understanding, but it doesn't replace the actual thing. Nonetheless, no one

Re: [HACKERS] Toward better documentation

2004-07-18 Thread Marc G. Fournier
On Sun, 18 Jul 2004, David Fetter wrote: What I am looking for is how the community feels about committing resources, which are in short supply, to putting more examples in the docs. I think this is a worthwhile effort, as it can pull in a larger group of people to do documentation, taking

Re: [HACKERS] Toward better documentation

2004-07-18 Thread Christopher Kings-Lynne
I see I have gotten off to a bad start here, and I apologize for not having made myself clearer. I did not suggest removing the principles items from the docs, nor did I suggest that anybody thought examples are a bad thing. What I am looking for is how the community feels about committing

Re: [HACKERS] Toward better documentation

2004-07-18 Thread Christopher Kings-Lynne
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

Re: [HACKERS] Toward better documentation

2004-07-18 Thread Andrew Dunstan
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