I don't think the "documentation sucks" can be used to model very well the issue, there is another very important thing: is it simple to use, and the base case

I don't think the "documentation sucks" can be used to model very well the issue, there is another very important thing: is it simple to use, and the base case is obvious, or is it over engineered? I think in the Twisted / Tornado issue there is some of this elements too. A lot of libs around here are, technically speaking, well coded, reliable, fast. But the API sucks. An example is the libpng, if you have some experience with it you'll understand. When an alternative with a clean API arise it's very hard to resist.