[docs] Adding Examples to Documentation

[Daniel Ellis]

Hello all,

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 <http://docs.python.org/library/itertools.html> 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?

Thanks,
Dan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20120725/709148c3/attachment.html>