>>>>> "RW" == Rick Wotnaz <[EMAIL PROTECTED]> 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
--
http://mail.python.org/mailman/listinfo/python-list
