[issue1579] logging documentation is unclear

[Kylotan]

Kylotan <kylotan at gmail.com> added the comment:

I think I gave some pretty clear details in my original submission. A
better example on the front page is needed rather than one that could be
confused with output methods. The example in 14.5.3 needs to not be one
big code dump with no explanation other than comments.

I could go on: the front page talks about named logger instances, and
yet the basic example completely omits any mention of such instances,
instead using module-level calls. You have to dig into the middle of the
example in 14.5.3 to see what this means, and because that example isn't
well explained, it's still not clear. It seems to have 2 loggers
attached to the root, but I can't see what benefit that gives, since
there's no example showing that logging sent to the root goes to the
children (does it?), nor does the reverse happen. Examples should show
one or two things, not try to demonstrate every feature in a code dump
and expect you to guess which parts do what.

As for submitting a patch, the whole problem with documentation is that
if you don't understand it, you can't use the software, so how could
such a person possibly know exactly what should go in the patch? It
needs to be written from the perspective of someone who has never used
it before, which right now it plainly isn't.

__________________________________
Tracker <report at bugs.python.org>
<http://bugs.python.org/issue1579>
__________________________________