As the author, I'm interested in improving the Pyramid docs. Can you elaborate on your issues with them? Did you notice the tutorials at http://docs.pylonshq.com/pyramid/dev/index.html#tutorials (lots of people seem to miss them).
- No clear visual distinction between links to glossary terms and links to further documentation. I like the glossary, but always ended up there without wanting to.
- I did find the tutorials, no issue there. (Only that the paster templates are a bit awkwardly named, but that's not a doc issue.)
- Especially the former BFG stuff, I'm thinking specifically about traversal, is explained in a way that probably makes a ton of sense to Zopeheads, but, at the time anyway, read more like a PhD thesis than like documentation.
- Again not strictly a documentation issue, but the fact that you can configure and use Pyramid in a ton of different ways means there's no straight path from getting started to actually getting something up and running, even with the tutorials. Not being opinionated about anything simply makes it very difficult to write good, forceful docs.
Traversal explaining: we're working on it (really). The docs have been rearranged and massaged a good bit, and they're being futher (professionally) edited now.
Flexibility: the best I can do about that without betraying the goals of the project is http://docs.pylonshq.com/pyramid/dev/designdefense.html#pyra... . I'm also working on a cookbook here: https://github.com/Pylons/pyramid_cookbook which should provide the tl;dr'ers with a way to perform common tasks without needing to read didactic explanations.
The responsiveness of Chris and Ben to actually fixing this kind of thing is amazing, and one of the major reasons we thought teaming up with them would be a good idea.