[issue28499] Logging module documentation needs a rework.

[Vinay Sajip]

Vinay Sajip  added the comment:

Closing, as no objections raised.

--
resolution:  -> not a bug
stage: needs patch -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Vinay Sajip]

Vinay Sajip  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Pierre Bousquie]

Pierre Bousquie added the comment:

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 :

>
> 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 
> 
> ___
>

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Florian Strzelecki]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Vinay Sajip]

Vinay Sajip added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Vinay Sajip]

Vinay Sajip added the comment:

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?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Pierre Bousquie]

Pierre Bousquie added the comment:

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
ndd 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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Ned Deily]

Changes by Ned Deily :


--
nosy: +vinay.sajip

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Pierre Bousquie]

New submission from Pierre Bousquie:

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!

--
assignee: docs@python
components: Documentation
messages: 279141
nosy: Pierre Bousquie, docs@python
priority: normal
severity: normal
status: open
title: Logging module documentation needs a rework.
type: enhancement
versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28499] Logging module documentation needs a rework.

[Stéphane Wirtel]

Stéphane Wirtel added the comment:

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 ?

--
nosy: +matrixise
stage:  -> needs patch
versions:  -Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com