RE: [Python-Dev] logging needs better documentation
Neal Becker writes:
There is only a single example in the logging module documentation. Please add more examples!
You are completely right... I am sure that those docs need to be improved. Would you be willing to write up some improved docs? If so, submit them to the patch manager on SourceForge, and we'll incorporate them into the next release possible (probably Python 2.5). If not, then it may have to wait until someone else has time to address it. -- Michael Chermside This email may contain confidential or privileged information. If you believe you have received the message in error, please notify the sender and delete the message without copying or disclosing it.
On Thursday 28 October 2004 12:23 pm, Chermside, Michael wrote:
Would you be willing to write up some improved docs? If so, submit them to the patch manager on SourceForge, and we'll incorporate them into the next release possible (probably Python 2.5). If not, then it may have to wait until someone else has time to address it.
Wrong or missing documentation is considered a bug, so improvements can (and should) be incorporated into 2.4 and backported to relevant maintenance branches. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
Michael> Neal Becker writes: >> There is only a single example in the logging module documentation. >> Please add more examples! Michael> You are completely right... I am sure that those docs need to Michael> be improved. Michael> Would you be willing to write up some improved docs? In an attempt to not discourage Neal, wholesale rewrites are not necessary. If you can submit plain text (or ReST) of an (expanded?) Examples section that would be great. One of us python-dev peons can convert your submission to LaTeX easily enough. (And Fred can correct our mistakes.) Skip
Skip Montanaro wrote:
Michael> Neal Becker writes: >> There is only a single example in the logging module documentation. >> Please add more examples!
Michael> You are completely right... I am sure that those docs need to Michael> be improved.
Michael> Would you be willing to write up some improved docs?
In an attempt to not discourage Neal, wholesale rewrites are not necessary. If you can submit plain text (or ReST) of an (expanded?) Examples section that would be great. One of us python-dev peons can convert your submission to LaTeX easily enough. (And Fred can correct our mistakes.)
You do realize, that this is the first time I even looked at logging, and I'm learning a few things with more effort than I think it should take. The fact remains, that I now have about 2 hours worth of experience with it, so don't you think I'm about the last person you should ask to write the doc?
>> In an attempt to not discourage Neal, wholesale rewrites are not >> necessary. If you can submit plain text (or ReST) of an (expanded?) >> Examples section that would be great. One of us python-dev peons can >> convert your submission to LaTeX easily enough. (And Fred can >> correct our mistakes.) >> Neal> You do realize, that this is the first time I even looked at Neal> logging, and I'm learning a few things with more effort than I Neal> think it should take. The fact remains, that I now have about 2 Neal> hours worth of experience with it, so don't you think I'm about Neal> the last person you should ask to write the doc? Don't shortchange yourself. The sorts of examples that would be useful to a rank beginner are often the most useful. Skip
Skip Montanaro wrote:
Neal> You do realize, that this is the first time I even looked at Neal> logging, and I'm learning a few things with more effort than I Neal> think it should take. The fact remains, that I now have about 2 Neal> hours worth of experience with it, so don't you think I'm about Neal> the last person you should ask to write the doc?
Don't shortchange yourself. The sorts of examples that would be useful to a rank beginner are often the most useful.
I'm with Skip - even a clear & concise description of what you found most confusing can help with the update process. Updating the docs to clarify a couple of specific points (or add in a few specific usage examples) is much easier (and far more likely to get done) than a general attempt to "improve the logging documentation". Cheers, Nick.
On Thursday 28 October 2004 01:25 pm, Neal D. Becker wrote:
You do realize, that this is the first time I even looked at logging, and I'm learning a few things with more effort than I think it should take. The fact remains, that I now have about 2 hours worth of experience with it, so don't you think I'm about the last person you should ask to write the doc?
Or perhaps the first? You know what you had trouble with, and what information would have helped you. If you manage to answer your questions about logging (with or without help), you'll know what it takes to answer the questions you had that weren't answered by the documentation. Having working answers in the docs is better than not having answers; we can refine later as needed. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
participants (5)
-
Chermside, Michael -
Fred L. Drake, Jr. -
Neal D. Becker -
Nick Coghlan -
Skip Montanaro