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
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
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
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
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
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
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
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