I only ever use the #python#documentation to look up specific facts, like constants or string format codes. If I need to understand something I look for a tutorial elsewhere.
The docs, like a lot of technical #Wikipedia articles, value accuracy and precision over clarity and understanding.
First make me understand the mental model. Then tweak the specifics. Don't start with the details. #pedagogy#learning
@davidr@daria This brings to mind something I often think about: documentation needs to be different things for different audiences, and I think it's often better to keep those different things separate. Case in point, introductory documentation (like tutorials) vs reference documentation (like constants and string format codes and other API listings). Right now most of the Python standard library documentation is closer to the reference end of the spectrum, but parts of it try to have a bit of a tutorial aspect as well, which I think is useful in small doses but it'd be easy to go overboard.
So my suggestion would be, the first thing to figure out is, who is the #Python documentation for? (Or, is it going to have different parts for different audiences?) IMO it's difficult/impossible to identify what changes would be improvements until that is clear.
The current Python documentation is strictly reference, and those reference pages should definitely not go anywhere. But it would be so lovely to add some tutorials and guides.
Add comment