[Grok-dev] Re: grok reference - what needs to be documented and what not

[Martijn Faassen]

Jan-Wijbrand Kolman wrote:
> On 5/29/07, Sebastian Ware <sebastian at urbantalk.se> wrote:
>> As a newbie user I would rather only see the documentation of the
>> functions and classes that I actually use. For me, less is more. If I
>> wanted to dig deeper, I would probably examine the code.
> 
> You have to keep in mind though, this *is* a *reference*. This implies
> completeness to me. The reference actually starts out with saying it
> should not be read as an introduction or tutorial to Grok.

I agree it should be complete. It can have references to tutorial text, 
but it shouldn't contain tutorial text itself. It *should* contain 
examples where possible though - those are often the most helpful part 
of the Python library reference.

But completeness needs to only be about published APIs. In Python, what 
is published and what is not is somewhat informal, but in Zope 3 we're a 
bit more formal than usual (interfaces.py), so we have a good to guide 
to go on.

Regards,

Martijn