gh-95271: Improve sqlite3 tutorial wording

[erlend-aasland]

Using the Diátaxis language of tutorials as a guideline.

• Issue: Improve the sqlite3 tutorial #95271

[erlend-aasland]

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.

[erlend-aasland]

Thanks for the initial review, Ezio! Tutorials are indeed hard :) PTAL

[CAM-Gerlach]

Sorry for the delay; was busy with several other things.

A bunch of generally minor suggestions, and a couple somewhat bigger comments (in line with @ezio-melotti 's feedback)

Overall, the biggest thing I felt was missing aside from a few explanations was actually connecting the tutorial with at least a basic meaningful real-world goal. Creating a database isn't an end, its a means, and along the lines of what you said on the issue, the tutorial would be more helpful, and also more engaging and even "fun" if it has at least some Connection to an actual use case.

Diataxis doesn't go into too much detail about this one way or the other, but a few passages relate:

A tutorial also needs to show the learner that they can be successful with the product - by having them do something both meaningful and attainable.

As long as the child managed to achieve something - however small - and enjoyed doing it, it will have laid down something in the construction of its technical expertise, that can be returned to and built upon next time.

it will have laid down something in the construction of its technical expertise, that can be returned to and built upon next time.

[CAM-Gerlach]

(Didn't meant to approve, meant to make that a comment sorry)

[ezio-melotti]

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¹.

Footnotes

1. despite the fact that at times we were borderline pilkunnussijat 🙃 ↩

[CAM-Gerlach]

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

[erlend-aasland]

I think we should consider landing this. Further improvements can be done incrementally, using Issues and PRs.

[CAM-Gerlach]

LGTM, thanks @erlend-aasland ! Two last tiny clarifications.

[erlend-aasland]

All right, I'm going to land this tonight. Great working with you all!

[miss-islington]

Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-96082 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-96083 is a backport of this pull request to the 3.10 branch.