Well, here is the point of view of a documentation translator. Most stdlib modules are documented with just a reference-style document, which of course is necessary. I think HOWTOs / understanding become needed if the module is particularly large or complex, or contains language concepts (e.g. async I/O or abstract base classes). On the other hand, I would say many if not most would benefit from a tutorial-like intro. As an example, take the ast module docs, which I translated:
I think this is a perfect example of a page that should be restructured.
- After two paragraphs of introduction with technical terms, it starts right away with a copy of the full Python grammar, which is hairy from the beginner point of view,
- Then it gives a detailed description of every single AST node,
- And only then, you find the information that you would have needed to start your journey with the module, namely the functions to parse an AST and manipulate it.
I would do it this way instead:
- An “AST overview” section demonstrating usage of
parse() and attribute access on AST nodes with examples at the REPL (perhaps also showing how pattern matching can be used elegantly on ASTs),
- Then the descriptions of the individual nodes,
- Finally, as an appendix, the Python grammar.
The first part roughly corresponds to a tutorial, the rest is reference. Again, for many modules, I don’t see a need for more, but from experience of walking through stdlib modules that I have no prior knowledge of to translate them, I do miss more tutorials.
Another example of a module that would benefit from a tutorial is the
re module. There are already quite good docs:
On the other hand, even on the HOWTO, you get to read some text that is a little heavy reading (at least for a primer on regexes) on metacharacters and stuff before learning how to execute a regular expression on a string. Here it might be beneficial to add a small tutorial with simple steps to get started with regexes.
An example that I consider good is the argparse docs. There are
- a tutorial (actually in the HOWTO section):
With the tutorial, you quickly get a basic grasp of how using
argparse feels like, and it gradually introduces more advanced concepts. Perhaps some of the material from the reference could be split into a HOWTO (e.g., how to use subparsers).
So, bottom line: in my opinion, the stdlib docs need more beginner-level material to help people get a basic grasp of stdlib modules before going into the fussy details.