Python doc problem example: gzip module (reprise)

[Charlton Wilbur]

>>>>> "RW" == Rick Wotnaz <desparn at wtf.com> writes:

    RW> Someone is sure to jump in now and point to sample code, which
    RW> nearly all reasonably major packages include. That's good
    RW> stuff.  With (for example) wxPython, it's the only useful
    RW> documentation, or rather, it's the only thing that makes the
    RW> wxWidgets documentation useful. Links to code samples in the
    RW> documentation would be fine in lieu of snippets of example
    RW> calls. But there's not enough of either in most documentation.

This is one of the places where Apple's Cocoa documentation shines:
there are frequently snippets of code accompanying more complicated
methods, which is nice, but there are a couple dozen small sample
programs that demonstrate how to use particular aspects of the
framework, available with full source code.

    RW> I would love to see examples for essentially every function
    RW> and method. And not just something that echoes the signature,
    RW> but some context to show how it might be useful. That would be
    RW> in the "intoxication" class of ultimate hopes. In most cases,
    RW> though, it would be *extremely* helpful for a casual user of
    RW> that part of the package.

Well, at some level you have to consider - who is the target audience
of the documentation?  There's usually a tradeoff involved in that
documentation aimed at novice users is usually not useful to advanced
users; there's also a ridiculous amount of work involved in making
*all* documentation available to all users, and there's usually a
better payoff involved in writing documentation that shows novice
users how to be intermediate users.

To take another example: in Cocoa, there's a well-defined and
well-documented approach to memory management, and conventions used
consistently throughout the whole Cocoa framework.  These conventions
could be documented over again for each and every class, but it's a
much better use of resources to document them once and to assume in
the documentation for each class that the reader is familiar with the
conventions.

Charlton


-- 
cwilbur at chromatico dot net
cwilbur at mac dot com