Thread: Toward better documentation

Toward better documentation

From
David Fetter
Date:
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!


Re: Toward better documentation

From
"Marc G. Fournier"
Date:
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


Re: Toward better documentation

From
Peter Eisentraut
Date:
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/



Re: Toward better documentation

From
David Fetter
Date:
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!


Re: Toward better documentation

From
"Marc G. Fournier"
Date:
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


Re: Toward better documentation

From
Christopher Kings-Lynne
Date:
> 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 :)


Re: Toward better documentation

From
Christopher Kings-Lynne
Date:
> 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



Re: Toward better documentation

From
Andrew Dunstan
Date:

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