I think one problem is actually complexity itself. One important goal of software engineering is to minimize complexity the irreducible complexity in a system and replace it with reducible complexity. The former makes it very hard to change things in predictable ways. The latter makes maintenance a lot easier too.

This isn't to say that sometimes complexity is unavoidable. I have never seen a simple ORM for example (and ORMs are by nature very complex, which is why I prefer not to use them). In these cases it isn't clear that complexity can be avoided, or that a simple entry point in the docs will help.

One thing I have found immensely helpful in dealing with complex modules is the idea of cookbooks. Cookbooks give you a series of contrived examples you can build stuff on. In this sense, perhaps, the synposis should focus on what a style of code might look like. The Moose documentation is a great example here. You have a simple example, sufficient for someone to read and get a sense of what the module kind of does. Then for real examples, you go to the cookbook.