[doc] improve sqlite3 docs

[erlend-aasland]

BPO	45677
Nosy	@stevendaprano, @willingc, @Mariatta, @miss-islington, @erlend-aasland, @AlexWaygood, @iafisher
PRs	bpo-45677: Reword first section of sqlite3 docs #29326 [3.10] bpo-45677: Reword first section of sqlite3 docs (GH-29326) #29566 [3.9] bpo-45677: Reword first section of sqlite3 docs (GH-29326) #29567

^{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']

[erlend-aasland]

The sqlite3 docs could need a little makeover. Here's some things that could be improved:

• avoid addressing the reader as "you"
• use an affermative tone
• establish a "Security Considerations" or "Common Mistakes" section, instead of littering the docs with warnings
• use imperative mood

See also:

• https://devguide.python.org/documenting/#style-guide

[stevendaprano]

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]

What is wrong with addressing the reader as "you"?

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.

Avoiding an affirmative tone goes directly against the style-guide you linked to, which recommends an affirmative (positive) tone:

Sorry, that was a language glitch; I'm not a native english speaker :) _Use_ an affirmative tone is of course correct.

[erlend-aasland]

(Nosying Mariatta and Carol from the CPython DWG)

[erlend-aasland]

See also discussion on Discourse: https://discuss.python.org/t/avoid-addressing-the-user-directly-when-writing-docs/11671

[willingc]

New changeset 6c5a312 by Erlend Egeberg Aasland in branch 'main':
bpo-45677: Reword first section of sqlite3 docs (bpo-29326)
6c5a312

[willingc]

New changeset 94dad5e by Miss Islington (bot) in branch '3.10':
bpo-45677: Reword first section of sqlite3 docs (GH-29326) (GH-29566)
94dad5e

[willingc]

New changeset a40d066 by Miss Islington (bot) in branch '3.9':
bpo-45677: Reword first section of sqlite3 docs (GH-29326) (GH-29567)
a40d066

[iafisher]

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]

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.