cpython
cpython copied to clipboard
python
gh-95271: Improve sqlite3 tutorial wording
I removed the :memory: tip; it is given in the reference. Perhaps we can instead start the tutorial off by first using a memory database, then using an on-disk database.
Thanks for the initial review, Ezio! Tutorials are indeed hard :) PTAL
Ok, I've tried to address more of your concerns, Ezio and CAM; thank you so much for feedback. I updated the SQL example as well; let me know how you think it works.[^1]
[^1]: Some other parts of the docs expand on the tutorial database; I think we should consider rewriting those to be stand-alone examples instead of leaning on the tutorial.
Also, another comment: maybe I'm overly concerned, but I do see a potential issue with the name
python.dbfor the database—users might think it is somehow "special" or related to Python itself, rather than that by chance happening to on the topic of Python releases. Maybereleases.dborpython_releases.dbwould be clearer and avoid any potentially special or confusing connotations?
I thought about that myself; I think we should either revert to the original example.db, or maybe slightly better: tutorial.db.
I think we're getting close to something usable, and hopefully something that is an improvement. I consider the following additions to the tutorial (maybe not in this PR):
- introducing the connection context manager for implicitly committing inserted data
- introducing the
sqlite3.Rowrow factory
- introducing the connection context manager for implicitly committing inserted data
How common is this? If it's like the builtin open(), where you want to use it pretty much all the time instead of calling file.close() manually, then it belongs in the tutorial. If instead calling .commit() manually is common enough, then you might cover the context manager in a separate howto.
You can also use .commit() manually, and then add a sentence like "It is also possible to use a context manager to commit directly. The above code is equivalent to::
- introducing the sqlite3.Row row factory
This sounds like it belongs in an howto too.
I'm also thinking whether it would be useful to have a "Further readings" list at the end of the tutorial that links to some of the howtos, or perhaps just a single link to the howto section (assuming the howtos are sorted from simpler to most complex).
I'm also thinking whether it would be useful to have a "Further readings" list at the end of the tutorial that links to some of the howtos, or perhaps just a single link to the howto section (assuming the howtos are sorted from simpler to most complex).
If the former, this could be a seealso directive block
I'm also thinking whether it would be useful to have a "Further readings" list at the end of the tutorial that links to some of the howtos, or perhaps just a single link to the howto section (assuming the howtos are sorted from simpler to most complex).
If the former, this could be a
seealsodirective block
I've also been thinking about this, and I think it is a good idea. I've also seen this in other well-structured docs (Django, amongst others, IIRC).
Somehow something didn't get submitted right, maybe?
That's quite possible.
I'll address the last rounds of review in the upcoming push.
Regarding tone: I also noticed that Diátaxis uses three variants. I think second person singular would be a good fit. IMO, some parts can use the imperative mood (such as the SQL injection attack warnings).
I pushed a new revision. I left some conversations open; feel free to close them.
In addition to addressing your highly appreciated review comments, I also tried to improve the overall tone of the tutorial.
I left out introducing the row factory and the context manager; since I now added a seealso section that point to the howto's, that should be taken care of.
I still think it would be nice to introduce the new sqlite3 CLI in the >= 3.12 version of the docs. It could be as simple as this:
First, let's check the SQLite version your sqlite3 module is built with by executing the command python -m sqlite3 -v. etc.
OTOH, the CLI may be better off with its own howto.
Sorry for the long delay on this; I got held up with other things and then was ~being lazy~ taking a break for a day.
I pushed a new revision. I left some conversations open; feel free to close them.
Just FYI, unless and until python/core-workflow#460 is resolved, I can't mark even my own review comments as resolved.
I thought about that myself; I think we should either revert to the original
example.db, or maybe slightly better:tutorial.db.
tutorial.db is what I would choose. It gives a good signal.
Daniele's reasons for using first person plural kind of sold me. That form is used in other parts of the stdlib docs, so it should be ok to use it here as well. Let me know what you think.
The tutorial looks great now! I left a few more comments if you feel like tweaking it a bit further, but otherwise I think it's ready to land. Undoubtedly a great improvement over the original.
Even though we're not done yet, I'd like to summarise my experiences so far.
Thank you so much, both of you, and of course Daniele, for your patience and incredibly helpful reviews; I could never have done this without your help.
I don't know about you, CAM and Ezio, but I think there are some lessons learned here (for me at least). Perhaps we could do a debrief on the up-coming docs meeting?
Here are some thoughts. IMO, the PR was premature:
- I thought I had a good grasp on how to apply Diátaxis, but there was a lot of details I had missed, or just forgot about while writing. Looking back at the reviews, I see that the reviews themselves changed during the course of the PR, probably because all of us were getting more and more into what applying Diátaxis is, and how to use it. (Pardon my clumsy wording there, but I hope you get the gist of it.) OTOH, the best way to learn something is to use it. It did not help that I'd read everything on the Diátaxis page up and down multiple times; I had to apply it and try to use it in order to discover that I was mostly fumbling in the dark, so it was a great learning experience 😃
- I should have discussed tone and langage before creating a PR. We now ended up with going back and forth with changes in one and language, before eventually settling on first person plural combined with the imperative mode.
- I should've come up with the example database and laid out the steps beforehand. Going back and forth with the examples was time-consuming, and unneeded. Once again, planning before doing is a good thing.
- There's probably more we could've done better; fill in the blanks[^1]
[^1]: or create a thread on discord 😆
- I see that the reviews themselves changed during the course of the PR ... I had to apply it and try to use it in order to discover that I was mostly fumbling in the dark, so it was a great learning experience 😃
- I should have discussed tone and langage before creating a PR.
- I should've come up with the example database and laid out the steps beforehand. Going back and forth with the examples was time-consuming, and unneeded. Once again, planning before doing is a good thing.
You will be glad to know that the entire second workshop ("Getting documentation done") attempts to address exactly these questions.
Please bring your thoughts and experiences. If you can take a couple of minutes, please write down your feelings about those experiences, which they are still fresh - we'll discuss those.
Going back and forth with the examples was time-consuming, and unneeded. Once again, planning before doing is a good thing.
I think we didn't quite know exactly what our destination was when we started, so we kept iterating and exploring different solutions until we were satisfied. Even though it was somewhat time-consuming, I don't think it was unneeded: as you mentioned, going through this whole process is what allowed us to learn. Had we just blindly followed some guidelines, we wouldn't have had the opportunity to try, compare, and discuss all our options and their pros and cons.
After going through this experience (and after the Diataxis workshop), we will in a much better position to take informed decisions while working on the documentation, and we will be able to do so more efficiently.
Also thank you for your patience and for listening to all our comments and bikesheddings[^1].
[^1]: despite the fact that at times we were borderline pilkunnussijat :upside_down_face:
OTOH, the best way to learn something is to use it. It did not help that I'd read everything on the Diátaxis page up and down multiple times; I had to apply it and try to use it in order to discover that I was mostly fumbling in the dark, so it was a great learning experience
+:100: That has definitely been my experience with Diataxis too—in general, I learn best by doing, and I've continually learned and re-learned new insights both in the overall course of experimenting with Diataxis, and just in this PR in particular. Funny enough, this seems to be one of the core messages of the Diataxis tutorial guidance itself:
A lesson entails a relationship between a teacher and a pupil. In all learning of this kind, learning takes place through what the pupil does.
Indeed, that seems to be how we've best learned Diataxis :)
I should have discussed tone and langage before creating a PR. We now ended up with going back and forth with changes in one and language, before eventually settling on first person plural combined with the imperative mode.
I should've come up with the example database and laid out the steps beforehand. Going back and forth with the examples was time-consuming, and unneeded. Once again, planning before doing is a good thing.
Maybe, but it would have been difficult to actually see how these worked out in context before seeing the whole thing, and once we've gone through it once (or a few times), guidelines can be documented in the dev guide and future PRs will go much smoother, without any back and forth. We might have spent the time planning, and then thrown all that out anyway when it didn't quite work in practice, or at least wasn't fully informed by it.
Typically, I'll write and have others review an outline (or more usually with Spyder, have whoever the writer is do that for me to review) for new docs, which can be very good at focusing discussion on the big picture—what needs to be included, what could be expended upon, what's missing and how to organize it all—before spending time on or getting too into the weeds of the details. Conversely, for re-writes like this, especially given its one of our first times grappling with applying Diataxis guidance to tutorials, it seems you did what planning you could, but we could only go so far before just going ahead with an implementation and iterating from there.
Also thank you for your patience and for listening to all our comments and bikesheddings
To be fair, that applies a lot more to me than to you, heh
I think we should consider landing this. Further improvements can be done incrementally, using Issues and PRs.
All right, I'm going to land this tonight. Great working with you all!
Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. 🐍🍒⛏🤖
