Diátaxis and Python documentation

[adorilson (Adorilson Bezerra)]

@nedbat

Finally, it’s hard to get agreement. You mentioned the “parameter highlight”, but I don’t think the pink sidebar helps: indented bullets are enough. The sidebar just takes up horizontal space that is in short supply on mobile devices.

Let me be more precise. I like that there is a highlight, but I also dislike the current style. I’ve saw ArgumentParser class use bullets. It is fine and better than os.copy_file_range, which describes all parameters in a paragraph. I had things like this in mind.

[pitrou (Antoine Pitrou)]

@Wombat

• The new threading build also lacks an instruction manual. Everything in the threading documentation assumes that a reader has already mastered thread programming and concepts in some other language.

Well, that sounds a reasonable approach to me. The json module doc, for example, doesn’t explain what JSON is. Neither does the http module doc explain what HTTP is.

If you want an introduction to JSON, HTTP or multi-threading, then you probably want to read something else than the documentation for the Python language.

This is especially true for multi-threading, which is difficult and full of pitfalls. Guiding beginners through it would require chapters of carefully-written, dedicated material.

[nedbat (Ned Batchelder)]

@pitrou

This is especially true for multi-threading, which is difficult and full of pitfalls. Guiding beginners through it would require chapters of carefully-written, dedicated material.

I agree in general that we can’t provide introductory material about every concept the stdlib builds on. But the threading module doesn’t even have simple examples of how to use the module. And considering the Python-specific confusion and complication around threading, we could definitely use some more explanation.