[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