Let me note that we already have nearly all the problems that have been mentioned as a negative for replacing bootstrap.py. Everyone that is checking out an old buildout or trying to update an old site is running into the fact that bootstrap.py is broken without extraordinary workarounds.
So, we already need to do some documentation to help these poor souls out of their bootstrap/setuptools hell. At the moment, it looks easiest to me to document the virtualenv/buildout approach.
I've just found time to come back & read this. I want to say thanks to Jens - for the virtualenv idea & everyone for the very helpful open discussion. I think the best thing that can be put in the docs is a clear admission that this area gets difficult at times... that should keep new adopters with us, rather than giving up!
Btw yesterday I found the following command which seems like it would help with version conflicts when I get them (is this obvious, or not?) In this example for plone.resource, it shows me what other products require it & what pins they apply: