Обсуждение: Toward better documentation
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? 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: > 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? 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>, 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