[Grok-dev] Re: grok reference - what needs to be documented and
faassen at startifact.com
Tue May 29 08:53:43 EDT 2007
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.
More information about the Grok-dev