classification
Title: Make datetime docs more user-friendly
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, bsolomon1124, cheryl.sabella, docs@python, miss-islington, p-ganssle
Priority: normal Keywords:

Created on 2019-05-18 20:17 by bsolomon1124, last changed 2019-09-12 14:37 by miss-islington. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 13410 merged bsolomon1124, 2019-05-18 20:17
PR 16056 merged miss-islington, 2019-09-12 14:22
Messages (4)
msg342813 - (view) Author: Brad Solomon (bsolomon1124) * Date: 2019-05-18 20:17
The datetime docs are chalk full of detail.  This is a positive aspect,
and represents a huge amount of work by Tim Peters and A.M. Kuchling.
However, it also may function as an obstacle for beginner readers and
those simply seeking to answer a basic question or see a straightforward
usage example.  Rather than seeing an example-based explanation of
a common use-case, they are bombarded with technical detail and
edge cases.

I propose some restructuring of the datetime docs with the goal of
making them more reader-friendly.  The goal is not to eliminate any
of the detail, but to restructure things so as to bring the "everyday"
parts into more prominent real estate.

The changes here all make an effort to reflect what's espoused by
"Documenting Python" at https://devguide.python.org/documenting/.

I have some additional changes in mind but wanted to put this here now
to gauge receptiveness to the existing changes.
msg342814 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-05-18 20:27
See also issue8822.
msg351774 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2019-09-11 09:19
New changeset 3fb1363fe87a24cdb2ee1dd9746f1c49046af958 by Paul Ganssle (Brad) in branch 'master':
Overhaul datetime documentation (GH-13410)
https://github.com/python/cpython/commit/3fb1363fe87a24cdb2ee1dd9746f1c49046af958
msg352180 - (view) Author: miss-islington (miss-islington) Date: 2019-09-12 14:37
New changeset 8976359c598f56825648f4e5397b78c5d14ea13c by Miss Islington (bot) in branch '3.8':
Overhaul datetime documentation (GH-13410)
https://github.com/python/cpython/commit/8976359c598f56825648f4e5397b78c5d14ea13c
History
Date User Action Args
2019-09-12 14:37:39miss-islingtonsetnosy: + miss-islington
messages: + msg352180
2019-09-12 14:22:37miss-islingtonsetpull_requests: + pull_request15679
2019-09-11 09:25:16p-gansslesetstatus: open -> closed
stage: resolved
resolution: fixed
versions: + Python 3.9, - Python 3.8
2019-09-11 09:19:08p-gansslesetmessages: + msg351774
2019-05-18 20:27:21cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg342814
2019-05-18 20:25:30cheryl.sabellasetnosy: + belopolsky, p-ganssle
2019-05-18 20:17:58bsolomon1124create