Re: [HACKERS] Toward better documentation

David Fetter wrote: Kind people, It's been pointed out to me that I tend to document by example , 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

Re: [HACKERS] Toward better documentation

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 thin

Re: [HACKERS] Toward better documentation

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 resou

Re: [HACKERS] Toward better documentation

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 some

Re: [HACKERS] Toward better documentation

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 o

Re: [HACKERS] Toward better documentation

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 Eisentr

Re: [HACKERS] 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 , e.g. My personal opinion is that this is a good thing, and should happen throughout the PostgreSQL documentation. However, this is not my decis

[HACKERS] Toward better documentation

Kind people, It's been pointed out to me that I tend to document by example , 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,