Clear questions and runnable code get the best and fastest answer |
|
PerlMonks |
Re: The problem of documenting complex modules.by einhverfr (Friar) |
on Jul 17, 2015 at 01:04 UTC ( [id://1135104]=note: print w/replies, xml ) | Need Help?? |
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 Section
Meditations
|
|