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

[Ethan Furman]

Stephen J. Turnbull wrote:
> They're not scared by that example.  What you need is a paragraph
> below it that says
> 
>     """
>     Do you think the above is all you should need?  If so, you're
>     right.  You can stop reading now.  If you think you need more,
>     we've got that, too.  Read on (you may need more coffee).
>     """ 

+1

Oleg Broytman writes:
> 
>  >    Better yet (IMHO) would be to split the huge page into "Logging: Simple
>  > start" and "Logging: Advanced usage (for the brave of of heart)".
> 
> Splitting is OK, but I disagree about the gloss "for the brave of
> heart".
> 
> In my experience, if it is a YAGNI, the complexity is nearly
> impenetrable.  If you *do* need it, it's not at all difficult to
> understand what the complexity is for, and it doesn't even look all
> that complex because it matches up with the problem you need to solve.
> 
> If the documentation is still a deterrent, that's a problem with the
> documentation and it should be improved.  AFAICT, making it clear that
> exporting all the internal flexibility is for those who need it, while
> most users will rarely need it, should be enough.  But I'm not a good
> test case, since I already am familiar with XEmacs's similar system.


I think I'm a pretty good test case -- knew nothing about logging, still 
don't know much, found documentation comprehensive but unweildy, and 
would *still* benefit from a more extensive (though still short) 
beginner's section, with the prominent paragraph stating I now know 
enough for simple cases.  :)

Oh, and awesome module, by the way.  Thank you.

~Ethan~