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

[Vinay Sajip]

Vinay Sajip added the comment:

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?

----------

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