classification
Title: [doc] improve sqlite3 docs
Type: Stage: patch review
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: AlexWaygood, Mariatta, docs@python, erlendaasland, iafisher, miss-islington, steven.daprano, willingc
Priority: normal Keywords: patch

Created on 2021-10-29 21:55 by erlendaasland, last changed 2021-11-21 16:53 by iafisher.

Pull Requests
URL Status Linked Edit
PR 29326 merged erlendaasland, 2021-10-29 22:00
PR 29566 merged miss-islington, 2021-11-15 22:23
PR 29567 merged miss-islington, 2021-11-15 22:23
Messages (9)
msg405349 - (view) Author: Erlend E. Aasland (erlendaasland) * (Python triager) Date: 2021-10-29 21:55
The sqlite3 docs could need a little makeover. Here's some things that could be improved:

- avoid addressing the reader as "you"
- avoid using affirmative tone
- establish a "Security Considerations" or "Common Mistakes" section, instead of littering the docs with warnings


See also:
- https://devguide.python.org/documenting/#style-guide
msg405352 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2021-10-29 22:39
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.
msg405397 - (view) Author: Erlend E. Aasland (erlendaasland) * (Python triager) Date: 2021-10-31 10:43
> 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.
msg405398 - (view) Author: Erlend E. Aasland (erlendaasland) * (Python triager) Date: 2021-10-31 10:46
(Nosying Mariatta and Carol from the CPython DWG)
msg405790 - (view) Author: Erlend E. Aasland (erlendaasland) * (Python triager) Date: 2021-11-05 12:29
See also discussion on Discourse: https://discuss.python.org/t/avoid-addressing-the-user-directly-when-writing-docs/11671
msg406362 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2021-11-15 22:22
New changeset 6c5a312fb6d92e879bf4c570b94e18bb9ffe5970 by Erlend Egeberg Aasland in branch 'main':
bpo-45677: Reword first section of `sqlite3` docs (#29326)
https://github.com/python/cpython/commit/6c5a312fb6d92e879bf4c570b94e18bb9ffe5970
msg406373 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2021-11-15 23:31
New changeset 94dad5e41e5863e03972f3f3646087fb591f73f9 by Miss Islington (bot) in branch '3.10':
bpo-45677: Reword first section of `sqlite3` docs (GH-29326) (GH-29566)
https://github.com/python/cpython/commit/94dad5e41e5863e03972f3f3646087fb591f73f9
msg406374 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2021-11-15 23:32
New changeset a40d066e8ef548b52eca2b0e27c219ddd7e11592 by Miss Islington (bot) in branch '3.9':
bpo-45677: Reword first section of `sqlite3` docs (GH-29326) (GH-29567)
https://github.com/python/cpython/commit/a40d066e8ef548b52eca2b0e27c219ddd7e11592
msg406730 - (view) Author: Ian Fisher (iafisher) * Date: 2021-11-21 16:53
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.
History
Date User Action Args
2021-11-21 16:53:06iafishersetnosy: + iafisher
messages: + msg406730
2021-11-15 23:32:35willingcsetmessages: + msg406374
2021-11-15 23:31:42willingcsetmessages: + msg406373
2021-11-15 22:23:07miss-islingtonsetpull_requests: + pull_request27815
2021-11-15 22:23:01miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request27814
2021-11-15 22:22:50willingcsetmessages: + msg406362
2021-11-05 12:29:14erlendaaslandsetmessages: + msg405790
2021-10-31 14:44:44AlexWaygoodsetnosy: + AlexWaygood
2021-10-31 10:46:03erlendaaslandsetnosy: + willingc, Mariatta
messages: + msg405398
2021-10-31 10:43:37erlendaaslandsetmessages: + msg405397
2021-10-29 22:39:33steven.dapranosetnosy: + steven.daprano
messages: + msg405352
2021-10-29 22:00:32erlendaaslandsetkeywords: + patch
stage: patch review
pull_requests: + pull_request27595
2021-10-29 21:55:04erlendaaslandcreate