At pyconf-fr 2016  Florian Strzelecki (@Exirel) made a great talk on how to make good documentation. At one time he asked "python logging doc?, did you realy found it clear and helpfull?" clear answer from the crowd: not at all.

Stephane Wirtel ask us (the unhappy folks) : Hey send a bug request, then the pull request and... i'll be there to help :).

So i'm here for first step: fill the bug issue.
I'm willing to fix this doc!

Hi Pierre,

Thank you for your issue and mainly for me ;-) Now, I am really interested by your feedback or the feedback of Florian Strzelecki because he can give us the organization of the sections and maybe we can try to improve the current documentation of the logging module with his recommendations.

Have you receive some recommendations from Florian ?

Hi stephane,

I have tweeted Florian and he is still interested.

I think the doc has a lot of information but does not organize it efficiently.

My notes from the conference:
- Logging reccord attribute is at 16.6.7 (middle of the doc) and that's a must to fine tune the message.

- Configuration: the "interesting" (read: must read for use in production) is in advanced tutorial: configuration...
https://docs.python.org/3.7/howto/logging.html#configuring-logging
aaaandd in :
https://docs.python.org/3.7/library/logging.config.html#module-logging.config

- Lots of information are also in the "See also" section.

and I had a personal fail time with logrotate... wich will work with python logging only if it used with WatchFileHandler.
https://docs.python.org/3.7/library/logging.handlers.html#logging.handlers.WatchedFileHandler

This is in the doc but only in handles section.

The current documentation makes it very simple for naive users, with the main section being a reference and leaving the details to the basic and advanced tutorials and the cookbook. This was deliberately done in response to earlier feedback that the documentation provided too much detail for simple usage, and numerous people at the time responded positively to that set of changes.

I'm happy to look at any proposals to improve the layout of the logging documentation, but remember that it must satisfy a lot of different audiences at different levels. Is there a link to Florian's talk somewhere? I couldn't find anything on the PyCon-fr 2016 website. Is it in English, and if not, is there a translation / transcript in English available?

s/leaving the details/leaving the more narrative aspects/

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!

I'm not sure this issue tracker is the best place to have an extended discussion about documentation - perhaps we should move this to a mailing list such as python-list.

I'm not sure what you read first, but the logging documentation main page has a box marked "Important" right at the top, which says: "This page contains the API reference information. For tutorial information and discussion of more advanced topics, see ..." and then links to the basic and advanced tutorials and cookbook.

The basic tutorial starts with information on when to use logging (including links to the convenient-for-beginners logging.XXX() functions), discusses the different logging levels, and then gives a simple example:

import logging
logging.warning('Watch out!')  # will print a message to the console
logging.info('I told you so')  # will not print anything

So I don't see where your statement "No example of quick usage (the first one is for `Logger.debug`, and that's not a generic one)" comes from, nor "The top-level function are documented at the end of the document, albeit they are the quickest way to use and understand `logging`". Although they are *listed* low down, there are *links* to them very early in the basic tutorial - in the very first paragraph of "When to use logging".

With reference to your rough proposed structure,

"Introduction to logging (with short example)" - the beginning of the basic tutorial does this.

"Configuration (a separated chapter to describe file format, dict schema, and stuff)" - outline is described in the advanced tutorial, details are found in the specific page on the API reference for the logging.config module.

"Module references (logging, logging.config, logging.handler, etc.)" - this is as it is now.

"Cookbook & Tutorials" - these are separated from the reference documentation but otherwise seem to broadly follow what you're referring to here.

Bear in mind that opinions on (and reactions to) documentation are fairly subjective. For example, you seem to find the Django documentation problematic, but I don't, and it's widely regarded as one of the best documentation sets for any Python project, and has contributed a lot to Django's success.

If you really want to take this on, I don't think a patch is the best way to proceed, because there will be a *lot* of changes due to things moving around, etc. and one would need to build the documentation from the changed sources to get the full effect of the changes, unlike when reviewing source code. Instead, you could create a project on ReadTheDocs which takes copies of the logging documentation source pages and changes them to provide your alternative vision of how the documentation should look. This will allow easier side-by-side comparison for anyone who wants to review and compare the alternatives. If it's generally felt (e.g. by people on python-dev) that the new version is better than the current, then bringing the changes back shouldn't be too hard. What do you think?

A project published on RTD looks like a very good idea. I'll give it a try!

Thanks for your feedback. I think we don't have the same opinion on how to organize parts and details, so it's on me to show something worth our times.

> you seem to find the Django documentation problematic

Yes, yet I found it to be one of the best out there too. I can enjoy something and still be critical about it. Even if I'm critical of the current logging documentation, there are plenty of good things here to keep, and if we want to compare, it's still far better than most documentation out there.

Thank you Vinay for your feedback.
RTD seems a very good start to me.

Florian thanks for joining :). I'm not leaving you alone on this!
I don't mind closing the "bug" request. It was mainly for Stéphane Wirtel
:)... but it's still "committing" :)

2016-11-02 13:47 GMT+01:00 Florian Strzelecki <report@bugs.python.org>:

>
> Florian Strzelecki added the comment:
>
> A project published on RTD looks like a very good idea. I'll give it a try!
>
> Thanks for your feedback. I think we don't have the same opinion on how to
> organize parts and details, so it's on me to show something worth our times.
>
> > you seem to find the Django documentation problematic
>
> Yes, yet I found it to be one of the best out there too. I can enjoy
> something and still be critical about it. Even if I'm critical of the
> current logging documentation, there are plenty of good things here to
> keep, and if we want to compare, it's still far better than most
> documentation out there.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue28499>
> _______________________________________
>

As there's (AFAIK) been no progress on this, I'd like to close this issue. Any objections?

Closing, as no objections raised.