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
<http://bugs.python.org/issue28499>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
