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?
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
---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to [EMAIL PROTECTED] so that your
message can get through to the mailing list cleanly
