One of the reasons I enjoy being involved in the Perl community is knowing that I can help people directly when it comes to evaluating my modules.
Recently, stephan48 in irc.perl.org/#poe needed to consider different options for doing some kind of multiprocess worker solution. A number of options were presented to him and I was lucky enough to garner his interest in trying out POEx::WorkerPool. It was a great learning experience in how people work through a distribution for evaluation.
The first thing he tried was to copy/paste my synopsis directly and run it. It had compile problems because I had made certain assumptions. For the most part, I wasn't expecting anyone to actually try to run it. In my defense, I consider the synopsis to just give a broad overview of the structure of use; not a full blown example useful for tweak-n-run solutions.
Second, he had no experience with the high level of tools on which POEx::WorkerPool is built. That meant that MooseX::Declare was foreign. The second stab he did at the code was attempting to shift $self from @_ which was giving him problems.
The third problem he encountered was the advanced and little used feature in POE that all exceptions in events are captured and propagated as a signal and as such requires a signal handler. Otherwise, the exception is devoured without so much as a peep to the developer. In my synopsis, I hadn't used all of the proper robust exception handling required to make sure things went smoothly. So in his attempt to simply have one worker with multiple queued jobs it failed because the method used immediately started the worker and prevented further job queue pushing. That failure was delivered as an exception. And to him, it was as if the magic wasn't happening at all. Only a single job would run.
All in all, we got him going eventually, and he came to the conclusion that perhaps this module wasn't the right tool for his job after all. And that's awesome that I was able to help him figure that out. I recognize that the tools that I build and use for my own projects may not be suitable for others. And while I see many advantages to using my solution for a fully scalable and maintainable system, sometimes, all you need is a little POE::Wheel::Run action to grease the wheels.
The upside is that I will be revisiting the documentation and perhaps build a mini-manual similar in structure to the Moose::Manual and the POE wiki. The casual developer has a problem to solve and doing 80% of the work in a well documented scaffold example really makes a difference.