We need something similar to the existing developer guide in the project site. Some common usage scenarios and examples.
Indeed. Where do you believe we should put it? The project space? Somewhere else? I'd honestly like a place with rst syntax ;P.
I think the project space would be ideal.
Well, I'm thinking about making two guides: one for users, the other for developers. Guide for users would just cover the basics like setting PYTHON_TARGETS, the other will say how and when to use eclasses.
First chapter on-line! http://www.gentoo.org/proj/en/Python/python-r1/user-guide.xml
I think the docs are good enough already to consider this one fixed.