[Python-Dev] Using logging in the stdlib and its unit tests

[Glenn Linderman]

On 12/11/2010 3:52 AM, Vinay Sajip wrote:
> I will try to incorporate more basic examples at the top of the documentation,
> but surely you don't want me to add more verbiage about basicConfig when your
> overall feeling is that there's too much documentation?

I try not to post unless I feel there is a new detail; yes the 8% is 
probably repetitive, but at present, going further, at least 
sequentially, does feel like a large mountain to climb... suddenly 
becoming significantly steeper there.

I really can't say much about the 92% of the documentation,  because of 
the mountain.

Whether the existing documentation can be reordered to avoid the steep 
part, but rather provide a gentle upward path, I cannot say.  If it is 
properly organized reference material, then probably adding more about 
something at the beginning is appropriate, to give the foundation, 
justification, and assistance for climbing the slope.

My overall feeling is not necessarily that there is too much 
documentation (there is a lot, but maybe that is a good thing, I should 
read it some week) but that it suffers in not providing useful 
information for the beginner at the front.  I've listed what I've 
gleaned here and tried to point out the things that I still don't know, 
and tried to point out where things became less than obvious along the 
way.  I do think it was primarily because the intro material is too 
brief and too disconnected, that I quit reading at the 8% mark (or so).  
If the rest of the large document were to be similarly disconnected, it 
wouldn't be worth my time to read it... and if I had to read it all, 
just to understand enough to get started with simple logging, then it 
would be faster to write my own, which is the path I took.  I suffer 
with my own being primitive, but I can tweak it when I need to.  I still 
don't fully understand the nuances between handlers and filters, and 
likely won't until I read more of the documentation.

Jumping directly to the documentation (at the 28% mark, I'd have had to 
read a long way to find it) for basicConfig per your links helps, but 
sadly,  because the first paragraph is full of the terms "logger", 
"handler", and "formatter", which I have only rudimentary ideas about 
what they do, being a beginner, I almost gave up again.  But the 
description of the valid keywords for **kwargs was actually 
understandable, at the end of that documentation.  I also learned that 
calling basicConfig more than once in a program is probably useless, and 
it should be nearly the first logger API called, if it is used.  The 
first paragraph should be split, perhaps: "Does basic configuration for 
the logging system." is almost redundant with the name, but is OK if 
first.  The rest of that paragraph, and the next three, should probably 
be moved after the list of kwargs keys and descriptions.  Yes, the word 
handler is used a bit, but it is associated there with concepts like 
file names and stream handles, and that eases the uncertainty; together 
with the simple example at the front, and the verbage there, I can see 
that I specify a file name, and it makes the logger log to that file :)  
And the level parameter is fine.  I'm less sure about format and datefmt 
and why I would want to specify them or how, and am surprised to find 
that format is to be used by a "handler" not a "formatter", but the 
simple example shows me I can leave those out for starters.

Personally, I suffer in writing documentation; when I attempt to do so, 
and people read it, they usually tell me that after about the third 
read, they finally understand it, but sadly it takes them three reads.  
It is interesting to be looking at the logger from the other side... 
maybe I'll be able to improve the documentation I write, after analyzing 
why the logger documentation was hard for me to approach.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101211/84082181/attachment.html>