[doc] improve sqlite3 docs #89840
Description
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2021-10-29.21:55:04.485>
labels = ['3.11', '3.9', '3.10', 'docs']
title = '[doc] improve sqlite3 docs'
updated_at = <Date 2021-11-21.16:53:06.411>
user = 'https://github.com/erlend-aasland'bugs.python.org fields:
activity = <Date 2021-11-21.16:53:06.411>
actor = 'iafisher'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-10-29.21:55:04.485>
creator = 'erlendaasland'
dependencies = []
files = []
hgrepos = []
issue_num = 45677
keywords = ['patch']
message_count = 9.0
messages = ['405349', '405352', '405397', '405398', '405790', '406362', '406373', '406374', '406730']
nosy_count = 8.0
nosy_names = ['steven.daprano', 'docs@python', 'willingc', 'Mariatta', 'miss-islington', 'erlendaasland', 'AlexWaygood', 'iafisher']
pr_nums = ['29326', '29566', '29567']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue45677'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
Activity
erlend-aasland commentedon Oct 29, 2021
The sqlite3 docs could need a little makeover. Here's some things that could be improved:
See also:
stevendaprano commentedon Oct 29, 2021
What is wrong with addressing the reader as "you"?
Avoiding an affirmative tone goes directly against the style-guide you linked to, which recommends an affirmative (positive) tone:
"The documentation focuses on affirmatively stating what the language does..."
The alternative would be to take a negative tone, focusing on what the library doesn't do.
erlend-aasland commentedon Oct 31, 2021
I remember this was discussed on python-dev last year (?). IIRC, the majority was in favour of changing the documentation to avoid addressing the reader personally. Let us ask the Documentation Workgroup over at Discourse. I'll create a topic.
Sorry, that was a language glitch; I'm not a native english speaker :) _Use_ an affirmative tone is of course correct.
erlend-aasland commentedon Oct 31, 2021
(Nosying Mariatta and Carol from the CPython DWG)
erlend-aasland commentedon Nov 5, 2021
See also discussion on Discourse: https://discuss.python.org/t/avoid-addressing-the-user-directly-when-writing-docs/11671
willingc commentedon Nov 15, 2021
New changeset 6c5a312 by Erlend Egeberg Aasland in branch 'main':
bpo-45677: Reword first section of
sqlite3docs (bpo-29326)6c5a312
willingc commentedon Nov 15, 2021
New changeset 94dad5e by Miss Islington (bot) in branch '3.10':
bpo-45677: Reword first section of
sqlite3docs (GH-29326) (GH-29566)94dad5e
willingc commentedon Nov 15, 2021
New changeset a40d066 by Miss Islington (bot) in branch '3.9':
bpo-45677: Reword first section of
sqlite3docs (GH-29326) (GH-29567)a40d066
iafisher commentedon Nov 21, 2021
I think it would also be helpful to make the examples at the top simpler/more idiomatic, e.g. using a context manager for the connection and calling conn.execute directly instead of spawning a cursor.
I think the information about the isolation_level parameter should also be displayed more prominently as many people are surprised to find sqlite3 automatically opening transactions.
erlend-aasland commentedon Jun 15, 2022
I'm closing this; the first section of the sqlite3 docs has been heavily improved, and recently, the exception section also got a make-over. The rest of the sqlite3 docs could still need improvement, but this particular issue is too vague, IMO. I suggest instead opening separate issues with concrete improvement proposals for sections where improvement is clearly needed.