[New-bugs-announce] [issue1579] logging documentation is unclear

[Kylotan]

New submission from Kylotan:

The documentation for the logging module is quite confusing, and (I am
told) seems to assume prior experience with the log4j utility or similar.

In particular:
 - the front page has a rather confusing example of the named hierarchy
system, which might mislead the reader by making them think it's about
file types (perhaps for log output) rather than just arbitrary naming
conventions.
 - section 14.5.3 attempts to explain this hierarchy, but does so via an
example for something else (ie. showing logging to multiple
destinations), and is just a large code-dump, mixing several concepts in
one example.

All in all, it could just do with being a lot more explicit about how
the naming convention and the hierarchy works, how each logger relates
to children/parents, and having a more transparent example on the first
page.

----------
components: Documentation
messages: 58347
nosy: Kylotan
severity: normal
status: open
title: logging documentation is unclear
versions: Python 2.5

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