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&gt;, 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

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 Eisentraut
http://developer.postgresql.org/~petere/

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 ever claimed that more examples would be a bad
thing.

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
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 load off people who
do coding. :)

Cheers,
D
--
David Fetter david@fetter.org http://fetter.org/
phone: +1 510 893 6100 mobile: +1 415 235 3778

Remember to vote!

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 load off people who do
coding. :)

Depends on who you feel should/would be doing these examples? Note that
there are *alot* of ppl out there that are not coders wondering what they
can do to contribute ... this is definitely one way.

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

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?

Sounds really great :)

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
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 load off people who
do coding. :)

If you are the resource, and you have supply, then go for it. Try to
assemble a team :) I know some people in the IRC channel were wanting
to help with docs.

Chris

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&gt;, 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?

I doubt you will find any objections to more examples. However I am sure
there would be many objections to substituting examples for reference
material. Rather, examples should illustrate and amplify the reference
material.

Also, there does need to be a consistent style in the docs. I suggest
one reasonable guideline, given the primary function of the docs as an
authoritative reference, and following the style mainly used already, is
'reference material first, examples following' in each relevant section.

If we were preparing docs intended primarily as teaching material, very
different principles might apply, but personally I don't see that as the
primary purpose of the docs.

cheers

andrew