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.
In reply to Re: The problem of documenting complex modules.
by einhverfr
in thread The problem of documenting complex modules.
by BrowserUk
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |