Datamodel documentation needs a reformat

[kj0 (Ken Jin)]

https://docs.python.org/3/reference/datamodel.html#types
Full disclaimer: I’m not saying we should rewrite the datamodel docs. What I’m suggesting instead is a reStructuredText reformat. Currently the formatting in that document is somewhat inconsistent. If you scroll towards the bottom, you’ll notice the recent additions have proper attribute, method and section markup whereas the older additions don’t.

• Objects should have their own sections instead of just being indented so that we can hyperlink to them.
• Object attributes and methods should be marked so that we can hyperlink to them. Currently they are just listed in a list format.

I don’t remember exactly which thread it is, but recently I saw a similar effort for sqllite3 docs and it was positively received.

[ezio-melotti]

@kj0

I don’t remember exactly which thread it is, but recently I saw a similar effort for sqllite3 docs and it was positively received.

Maybe you mean this thread?

Explicit parameter list in function documentation

In other news, I drafted another example for sqlite3.connect(), in response to @erlendaasland pointing out some serious issues with the current structure on a recent PR: [image]

The sqlite3 docs are also being updated by @erlendaasland to follow the Diataxis framework

• Adopting the Diátaxis framework for Python documentation
• issue: https://github.com/python/cpython/issues/94635
• PR: https://github.com/python/cpython/pull/94636

Updating the rst markup to be consistent is somewhat orthogonal to Diataxis, but if we are going to do it, we might as well keep the Diataxis principles in mind.

[CAM-Gerlach]

I’d certainly agree it would be much better served with a more structured, consistent format, as per Diataxis (which, as I frequently remind everyone, isn’t just about moving things around, but also improving the docs that are already in each of the categories—reference, in this case—to better serve their intended audience):

The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way.

Respect the structure of the machinery

The way a map corresponds to the territory it represents helps us use the former to find our way through the latter. It should be the same with documentation: the structure of the documentation should mirror the structure of the product, so that the user can work their way through them at the same time.

In the case of code, this means arranging the sections of reference documentation to follow the architecture of the software, where possible.

Be consistant

Reference material benefits from consistency. Be consistent, in structure, language, terminology, tone.

This also helps a number of other things, such as when we’re trying to backlink in with the new PEP canonical docs banner.

This is certainly something I could help tackle, but I only have so many hours in a day and seemingly no end to the amount of docs that need help, not to mention everything else I’m engaged in just with open source.

As a core dev, I’m sure you’re busy too, but any help you could offer in this would I’m sure be much appreciated by all. I’m happy to help tag-team and review your PRs on behalf of the proofreaders/docs team as I did with Erlend’s that @ezio-melotti mentioned, which has been a very fruitful collaboration for us thus far.

[kj0 (Ken Jin)]

I plan to work on this (I wouldn’t have mentioned it here otherwise). However, I have a long list of things on my to-do list so it might be some time before I get to it.

[ezio-melotti]

Feel free to add me as a reviewer once you do (this also applies to any other doc-related issue/PR, especially if they are about Diataxis).