A bit ago, after talking with Guido on the the core developers group, I was working on examples for areas of the documentation that I felt would be helpful to have examples for (particularly itertools, but also functools and os). I received some feedback from the group once I submitted some new documentation, but it never moved much further.

I was hoping to start a discussion here to see whether others felt that examples of code usage would be worthwhile, and if so, how we could organize these into sections.

Taking itertools as an example, there are a lot of great implementation details, as well as recipes that combine the various functions, but the actual examples of how to use the library are small and potentially confusing for someone using the library for the first time. I know people go to the documentation for various reasons, so I don't think removing these sections would be wise, but what do you all think about adding an "Example Usage" section that lists some concise and easy ways to get up and running with the library?

Many documentation pages have "example" sections with usage samples. When these make sense and can be made sufficiently small and expressive, they're very helpful. So I suggest to propose something more concrete. I.e. create an issue in the bug tracker and add a patch with some examples for the module you want to document. Add relevant persons to the nosy list (http://docs.python.org/devguide/experts.html), and hopefully someone will take a look. Eli