On 12/8/2010 4:15 AM, Vinay Sajip wrote:
You're complaining about too much documentation?! Don't measure it by weight!
On 12/8/2010 5:57 AM, Vinay Sajip wrote:
Of course I understand I could be wrong
about this, but I don't recall when a stdlib maintainer has said to me, "I want
to start using logging in stdlib module XXX, but can't justify it because ..."
So I'm a fairly new Python user, but 30 years programming
experience.
When I first looked at the Python logging facility (and again today,
when I looked again), I found a simple example of debugging
logging. Then a bunch of stuff about how to configure rotating
logs. Then something about logging levels. And then a dissertation
on the theory of loggers "The logging library takes a modular
approach and offers the several categories
of components: loggers, handlers, filters, and formatters." And I
hadn't gotten through 10% of the documentation yet, per the
scrollbar.
My reaction the first time was "Sounds sophisticated and complex. I
think I'll do something simpler for now, and maybe someday, when I
have a spare week, I'll read the documentation and see if the
benefits are worth the effort."
OK, so now you've discovered that too much documentation can be a
turn off... at least, if it is presented from the top to describe
the sophistication of the facility, rather than how easy it is to
use (if it is, I still haven't gotten to 10%, and I still don't know
that).