-
-
Notifications
You must be signed in to change notification settings - Fork 30.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Restructure the sqlite3 docs table-of-contents #94635
Comments
cc. @CAM-Gerlach #diataxis |
Maybe it is better to swap Concepts and Guides:
|
FWIW, I teach sqlite3 directly from the current docs. They are VERY useful as-is. I would like to know what problem is being solved here. From what I can tell, no user has ever had issues with the current arrangement. |
Thanks!
The top-level structure is flat. I'm suggesting to organise the sections under headings: Current layoutTable of Contentssqlite3 — DB-API 2.0 interface for SQLite databases
After this PRTable of Contentssqlite3 — DB-API 2.0 interface for SQLite databases
|
As I view it, this is a weak argument for keeping things as they are. There can be room for improvement, both in docs and code, even though no-one has taken the steps to create a ticket on the bug tracker. |
At least per Diataxis, the most natural flow would have Explanations ("Concepts") last, since they are higher-level discussions of less urgent immediacy to most users...though, at least one of the "Concepts" subsections doesn't quite fit the "Explanation" mold, as discussed on the PR, and phrasing them as "Concepts" conveys more primacy than "Explanations".
Given your perspective, any additional details you could provide would be quite helpful. Are you referring to useful to yourself as an instructor? Or to your students—and if so, it would be helpful to know how you're evaluating that? Are they being used as a tutorial, reference, how-to/guide, or explanation—or some combination? And for context, what sort(s) of students are we talking here? Also, do you have any specific concerns you could share about the proposed structure and its effect on your teaching and your students? |
pythonGH-95269) (cherry picked from commit 2e35a13) Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
pythonGH-95269) (cherry picked from commit 2e35a13) Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
#94636) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
…o sqlite3 docs (pythonGH-94636) Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>. (cherry picked from commit 6c439b9) Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
In pythongh-95269, the seealso note incorrectly ended up in the 'Tutorial' section.
I suggest to remove the Introduction heading (it serves little purpose), and then close this issue. |
There are still a couple things that need doing:
Would you like me to open PRs for these, or do them yourself? |
(cherry picked from commit ede771c) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
(cherry picked from commit ede771c) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
Sure, go ahead :) |
FTR, Daniele's Camera docs repeat "How-to" for subsections: |
Will do shortly 👍 I've indeed come around to your reasoning on this 😄 |
Thanks, opened as #96136 |
…rs to reference (#96136) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
…efault adapters to reference (pythonGH-96136) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>. (cherry picked from commit 6bda5b8) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
…efault adapters to reference (pythonGH-96136) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>. (cherry picked from commit 6bda5b8) Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
AFAICS, we can close this. Thanks CAM and Ezio! |
…adapters to reference (python#96136) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com> Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Thanks to you for doing most of the work! |
The current docs are laid out more or less like this:
Suggesting to make the following improvements:
Implemented by (all backported to 3.11 and 3.10):
The text was updated successfully, but these errors were encountered: