[docs] [issue28499] Logging module documentation needs a rework.

[Florian Strzelecki]

Florian Strzelecki added the comment:

Hi! Sorry for the delay.

I published my slides on speaker deck: https://speakerdeck.com/exirel/read-and-write-the-doc
It contains only my main ideas and key concepts, since I prefer to talk more than just read slides to the public. I hope Pycon FR's organizers will be able to upload videos soon - it'll need translation for non-French speaker, too.

Thanks for creating this issue and for all your comments. I'll try to talk more here, but I'm not sure how we should proceed - so let's start a conversation?

In my talk, I rant a bit about two documentations: Django's documentation, and Python Logging's documentation. Both have, in my opinion, an issue with their organization: the Django one tend to scatter information around multiple chapters, and the Logging one, albeit properly compacted, fail to quickly answer beginner's questions and advanced user's needs.

Don't get me wrong: there is a lot of content here. Most of the question one may ask have an answer, lying here or there. After all, I was able to use the Configure File Format, once I had read the reference documentation for `logging`, `logging.config`, both tutorials, and the cookbook. My point is: I value a lot this documentation, but my experience as a beginner wasn't that good, and my current experience as an advanced user could be improved.

I remember the first time I read the documentation. I was reading an application's source code that used a `logging.config.dictConfig`, and I couldn't understand how it worked. How does each level in loggers and handlers work? How to change the format of each log? Does it work in multiple threads? In multiple process? Why is there a `logging.getLogger('something')`? How does it know my configuration? How can I output logs in my console and still write them? Can I call `getLogger` before I configure anything?

Take the main page (https://docs.python.org/3.7/library/logging.html):

* Hard to find a "How to configure logging" link,
* No description of the logging flow (it can be found in the advanced tutorial),
* No example of quick usage (the first one is for `Logger.debug`, and that's not a generic one),
* The top-level function are documented at the end of the document, albeit they are the quickest way to use and understand `logging`
* The "See also" part (which provide easy access to more content) is far far away at the bottom of the document.

And I think there are many other small issues regarding content organization.

I think there are (at least) 2 ways to look at these:

* Rework the overall structure,
* Focus on example.

I didn't think a lot about a better structure, so something like that is just a quick draft:

* Introduction to logging (with short example)
* Logging usage (how logging works - the Advanced Tutorial talk a lot about that)
* Configuration (a separated chapter to describe file format, dict schema, and stuff)
* Module references (logging, logging.config, logging.handler, etc.)
* Cookbook & Tutorials

(Each part in a separated chapter/sub-chapter)

I also think that the documentation should be able to answer these questions:

* As a beginner, how do I start? How should I learn logging?
* As experienced, how do I jump directly to what I want to know? (config, format, etc.)
* As advanced, how do I extend logging in my application?

I don't think a beginner needs to know what a LogRecord is, but they'll need to know what keys to use in their formatter in their basicConfig/dictConfig. And an advanced dev shouldn't spend minutes to fetch the documentation to finally found how to use their own LogRecord object in their logger.

---

Welp. That's a lot of text for now. I'm still not sure how to help nor how to begin with that. I never tried to make a push request to Python, and I don't know if I should try to submit a diff or not. Also, there is so much more than just that (I didn't talk about the "focus on example" part).

Last but not least, thanks for your attention!

----------
nosy: +Florian Strzelecki

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue28499>
_______________________________________