I’ll preface this by saying a) I have no answers, and b) y’all doc experts might already be thinking about this, in which case, yay!
Recently, the Steering Council considered PEP 728 which enhances typing.TypedDict for Python 3.15. While researching the PEP, of course I went to read the documentation for TypedDict and tried to think about how the new additions would be documented. In @corona10’s announcement of our acceptance of the PEP, he mentioned the thoughts – or maybe concerns – that occurred to me during those deliberations, hence this post.
I love good documentation, and Python’s is thorough and exceptional. But I also think it’s true that some of our documentation is really difficult to read and navigate exactly because it’s so extensive. On my big monitor, TypedDict for Python 3.13 alone is probably 5 vertical pages of content. Yes, my font is a little bigger and increasing as my eyes get worse but still, it’s a lot!
Another example that I ran across recently is the sys module which is chalk full of goodness. I’m sure you can come up with other examples.
Python’s documentation is only growing over time, so this is going to come up more and more. While as I mentioned I have no answers, I know that the answer isn’t to reduce our documentation or make it less thorough. Ultimately it’s a good thing that all of our features are described generally quite well, and I’ve even suggested we add more documentation. I’m just wondering out loud if anybody has thought about ways to organize or present our docs so they are easier to consume?
We have certainly been talking about it, but no action yet!
In general, I think we do need to split things up into smaller chunks.
It will help SEO, so people can find what they need quicker via search. We’d need to make sure that old links still point somewhere relevant, through orphan pages or redirects.
I think the typing docs are a bit of a special case here, because the docs.python.org typing docs focus on runtime behavior, because it’s the module documentation and therefore lists the module’s contents, but a lot of what users are going to look for in typing documentation is not about runtime behavior. Indeed much of the runtime behavior is not very relevant to most users. For example, the linked TypedDict docs prominently mention the __total__ attribute, but it is only relevant if you’re introspecting the TypedDict object at runtime, which most users won’t need to do.
Ideally we should have a separate set of documents focused on how to use the type system, either under typing.python.org or docs.python.org. But putting that together would be a lot of work that most people don’t have the time for.
I’m musing here, but I could see in the not too distant future that there would be a future frontend that uses natural language to surface and compose customized documentation for a user.
Here we’ve discussed listing modules in alphabetical order.
Last days, I’ve analyzed the library/index page. So, besides the alphabetical order, I have two more suggestions:
Moving the module categories to a new page, replacing all of them in library/index by a meta-category, maybe “Standard library modules“
Reviewing every category. For instance, we can rearrange the Tk’s stuff, something like:
Graphical user interfaces
turtle — Turtle graphics
IDLE
Graphical User Interfaces with Tk
Here, the modules are listed on top. After them comes everything that isn’t a module itself. Also, I ask myself if IDLE shouldn’t be in the Development Tools category.
It seems to me that the biggest psychological blocker is that it seems like this needs to be done all at once. (Or at least with a clear plan for what the result should look like, which is largely equivalent – you’d need a proof of concept to discuss this.)
IMO, we need to tackle this in pieces. For example, If we want to split up the Built-in types page, I don’t see it happening in a single PR.
The first step should be to take a section from and move it to its own page. We’d need to accept that this will make the docs less consistent (there’s no guarantee that volunteers will tackle the remaining sections in any reasonable time), and that it won’t provide all the answers about what we should do with the other sections, but it would leave a clearer path to fixing issues in the other sections.
Similarly for sys – if we find a good category name for some of the API, let’s add a section for it, even if it leaves an ugly “misc” section with everything else, and breaks the alphabetical ordering.
One thing Daniele mentioned at the Diátaxis worshop is that it’s OK for a PR to leave the docs looking messier than before, if it highlights a pre-existing flaw. A “misc” section is ugly, but appropriate for a grab-bag of unrelated stuff – it highlights the need for restructuring, rather than shoving it under the carpet. It can serve as a call to action.
(Of course, “misc” can just as easily be an unnamed section at the start of the page, if we’re not ready for calls to action yet.)
One thing that needs to be done right from the start is making sure existing URLs continue to work.
The benefit would have to be huge to make it worth breaking all the incoming links to the docs from external sources. StackOverflow has 2 million python questions. Many of the answers link to the docs. Also blog posts, third-party documentation, comments in code, discussions in GitHub etc.
“Which module belongs to which category” is a subjective issue. I do find the categories quite useful in providing a focused overview of the modules, but indeed many modules don’t fall cleanly into categories, nor do the existing categories always make the most sense to me. For example, I never understand why dataclasses — Data Classes — Python 3.13.7 documentation and abc (the module which defines ABCMeta, not collections.abc) are part of the Python Runtime Services (the name of which isn’t too helpfully descriptive) instead of Data Types. I also fail to see the similarity between dataclasses and sys. Or tomllib belonging to File Formats while json lives in Internet Data Handling , with the docs on json stating that “This module exposes an API familiar to users of the standard library marshal and pickle modules."
Whether and how to reorganize the docs is a matter of judgement. Fortunately in any case the actual existing URLs are flat structured and are unlikely to break after recategorizing the pages.
I’d just like to add, unlike the text, the translations will not move with it. This does not affect TX translations as the TM will fill it back up, but for the several PR based efforts will see a large chunk of work disappear (they can write a script that works like the TM, so I suggest that be done in preparation for such restructuring).
It should be possible to include the modules in multiple categories. Categories would be more like tags rather than directories. For example, `json` could be both in Data Types and Internet Data Handling.
but still, it’s a lot!