# Restructuring the stdlib docs

**URL:** <https://discuss.python.org/t/restructuring-the-stdlib-docs/102506>\
**Category:** Documentation\
**Created:** [August 15, 2025, 9:56pm UTC](https://discuss.python.org/t/restructuring-the-stdlib-docs/102506 "2025-08-15T21:56:00Z")\
**Posts on this page:** 1\
**Showing post:** 7

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [August 18, 2025, 9:35am UTC](https://discuss.python.org/t/restructuring-the-stdlib-docs/102506/7 "2025-08-18T09:35:22Z")

</div>

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](https://docs.python.org/3/library/stdtypes.html) 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.

---

_[View the full topic](https://discuss.python.org/t/restructuring-the-stdlib-docs/102506)._