Repository navigation
Improve the sqlite3 tutorial #95271
Description
Improve the tutorial using Diataxis as a guideline: https://diataxis.fr/tutorials/
The current tutorial is quite good, but it could make use of some improvements. The first that comes to mind, is:
- Provide a clear picture before we start the tutorial
- Some parts of the tutorial could make use clearer steps.
- Make the wording more to the point; avoid options and alternatives.
- Offer only minimum necessary explanation
Suggesting to split this up into multiple PRs, for the reviewers convenience.
Metadata
Metadata
Assignees
Labels
Projects
- Status
Activity
erlend-aasland commentedon Jul 27, 2022
cc. @CAM-Gerlach & @ezio-melotti #diataxis
erlend-aasland commentedon Jul 27, 2022
Currently, the tutorial uses two different database examples (one stock exchange example, and a more recent programming language info example). We should aim to use just a single example database for the tutorial. That example database could also be used in other examples, sprinkled across the reference and in how-to's1.
So, I'm not particularly fond of the stock exchange example; it works well, but it is ... maybe a little bit dull2? Would it be more fun for the aspiring Python SQLite database programmer if we expand on the programming languages example? Or perhaps something else?
Quoting Diátaxis, I think this touches upon the first item in this list; the example must be meaningful for the tutorial to be meaningful:
Footnotes
It will probably not make sense to just use one grand example database for the whole sqlite3 docs; e.g., the type detection and the user-defined functions work best with stand-alone examples. ↩
No offence meant to the original author; it's just my personal opinion. ↩
CAM-Gerlach commentedon Jul 28, 2022
Maybe spice it up with some cryptocurrency? That's bound to be...exciting...these days... /s
As to the example, I'm really not sure. While being a relative subject matter n00b has been helpful in reviewing the docs from a more beginner perspective, I don't really have the required background to suggest something in this specific question, sorry.
pythongh-95271: Extract placeholders howto from sqlite3 tutorial
gh-95271: Extract placeholders howto from sqlite3 tutorial (#95522)
[3.11] pythongh-95271: Extract placeholders howto from sqlite3 tutori…
[3.10] pythongh-95271: Extract placeholders howto from sqlite3 tutori…
[3.10] gh-95271: Extract placeholders howto from sqlite3 tutorial (GH…
[3.11] gh-95271: Extract placeholders howto from sqlite3 tutorial (GH…
pythongh-95271: Improve sqlite3 tutorial wording
pythongh-95271: Extract placeholders howto from sqlite3 tutorial (pyt…
gh-95271: Rework sqlite3 tutorial (#95749)
pythongh-95271: Rework sqlite3 tutorial (pythonGH-95749)
pythongh-95271: Rework sqlite3 tutorial (pythonGH-95749)
gh-95271: Rework sqlite3 tutorial (GH-95749)
gh-95271: Rework sqlite3 tutorial (GH-95749)