A little while ago I posted about the need for a mock database driver in Perl. Well, DBD::Mock has now hit the CPAN with actual tests and docs, which are pretty good I think, especially for a module that has a fairly limited set of use cases.
Now that I think of it, it's probably easier to write documentation for a component that has limited uses. You can cover a significant portion (where 'significant' approaches 100%) of how people will use it and thus deal with the examples and pitfalls concretely one by one rather than abstractly. The concrete part is the trick -- I don't know anyone who learns better from abstractions than examples.
Anyway, in my opensource documentation I'm trying to be much better about using examples to illustrate what's going on and how to use a module. Code and/or configuration speaks quite loudly in matters like this.