Issue1579
This issue tracker has been migrated to GitHub,
and is currently read-only.
For more information,
see the GitHub FAQs in the Python's Developer Guide.
Created on 2007-12-10 15:23 by Kylotan, last changed 2022-04-11 14:56 by admin. This issue is now closed.
Messages (5) | |||
---|---|---|---|
msg58347 - (view) | Author: (Kylotan) | Date: 2007-12-10 15:23 | |
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. |
|||
msg58348 - (view) | Author: Facundo Batista (facundobatista) * | Date: 2007-12-10 15:27 | |
Do you think that can came up with a patch for this? Just the paragraphs better written, or a better example, that would be great! Thanks! |
|||
msg64684 - (view) | Author: Vinay Sajip (vinay.sajip) * | Date: 2008-03-29 06:35 | |
I don't believe that the logging documentation is particularly unclear, though of course it could always be improved, like most other documentation ;-) It certainly does not rely on prior experience of log4j; though some of the concepts are similar, the details are not. As per Facundo's comment, I'll certainly look at documentation patches - but I'll close this issue for now. If you would like to reopen, please submit a patch with specific suggested improvements. |
|||
msg64695 - (view) | Author: (Kylotan) | Date: 2008-03-29 13:50 | |
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. |
|||
msg64738 - (view) | Author: Vinay Sajip (vinay.sajip) * | Date: 2008-03-30 00:56 | |
In your original submission, you said: "... 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." What the front page says is: "Each [Logger] instance has a name, and they are conceptually arranged in a name space hierarchy using dots (periods) as separators. For example, a logger named "scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf". Logger names can be anything you want, and indicate the area of an application in which a logged message originates." Notice the last sentence, which clearly (to me) states that logger names can by anything you want, i.e. an arbitrary naming convention. Although the examples given were "scan.text", "scan.html" and "scan.pdf", I don't believe the average user would confuse this with file types for log output, unless they skimmed the paragraph. The paragraph does not mention file types anywhere else, and nor do the next few paragraphs. The example in section 14.5.3 is fairly well commented, so IMO it's misrepresenting it a little to call it a "code dump". It's not the first example, either - a number of shorter examples are shown earlier in the documentation. When the logging package was introduced into Python back in version 2.3, there were some valid comments from people about lack of examples and lack of clarity in the documentation. This was rectified over time, and your comment is the first one for several months about documentation clarity. About documentation, it could always be argued that it could be clearer, because there's bound to be someone who doesn't understand it. But maintenance of this package (and Python) is a spare-time activity for most of us, and a number of competing priorities have to be traded off when deciding how to spend that time. I have spent a fair amount of time over the months improving the documentation, as have others, to the point where we don't get many comments about it; hence, it's time, from my point of view, to scratch other itches. If people feel strongly enough about it, they'll submit specific ideas or patches, which can be easily incorporated into the documentation. (You can look at the history of changes to the logging documentation in SVN to see that it updated reasonably often.) Simply stating that it "is quite confusing" is so open ended that an effort to make it less confusing could take a very long time, and that's why I invited a patch: I got the impression that you now understand how the hierarchy etc. works, even if you didn't straight away. If you are still having difficulty understanding some aspects of the package, please post on comp.lang.python: you will see that queries are reasonably promptly answered, not always by core developers but often by other users of the logging package. |
History | |||
---|---|---|---|
Date | User | Action | Args |
2022-04-11 14:56:28 | admin | set | github: 45920 |
2008-03-30 00:56:36 | vinay.sajip | set | messages: + msg64738 |
2008-03-29 13:50:49 | Kylotan | set | messages: + msg64695 |
2008-03-29 06:35:51 | vinay.sajip | set | status: open -> closed resolution: not a bug messages: + msg64684 nosy: + vinay.sajip |
2008-01-28 19:37:28 | christian.heimes | set | priority: normal keywords: + easy type: enhancement versions: + Python 2.6, - Python 2.5 |
2007-12-10 15:27:23 | facundobatista | set | nosy:
+ facundobatista messages: + msg58348 |
2007-12-10 15:23:14 | Kylotan | create |