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~ _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
