Spot on.
I'm not as fast as I used to be, but I'm a fairly talented and reasonably accomplished software architect and designer. I find it fun to design and code the solution, but when the time comes that I surrender to using CPAN, it is almost always because I am interested in saving time. The lengthy list of other benefits of using CPAN are more or less incidental for me, most of the time.
I have had many modules I've simply ceased trying to use because of the time investment required to use them -- I could be writing the code to accomplish the task and thus having fun, and have an API that makes sense to me; or I can suck down a metric ton of coffee and Mt. Dew in order to stay awake reading documentation.
I'm currently in a holding pattern on one of my personal projects because I have a module that does what I need, and the algorithm is sufficiently complex that even I can tell it will be faster to learn to use the module.
The working snippet I have from another Monk's post showed me which subroutine/method is likely to yield what I want, and preliminary tests show it truly does the heavy lifting -- I just need to adjust its results.
The PerlMonks node was my "in".
Unfortunately, the documentation chooses to teach how the algorithm works, and wisely approaches it by degrees, showing how to use smaller, easier-to-understand functions first, and the method I need to use is naturally dead last on the list.
The old hacker in me wants to just reverse-engineer the sample code, figure out how the method works, apply that knowledge to the problem I'm trying to solve, and just get on with it.
However, I'm an algorithm junkie; going through the motions as presented in the module would be juicy reading and would likely expand my knowledge base on problem-solving algorithms very nicely. But that will take time. So I'm resisting temptation now to take my in and run with it -- but make no mistake, that is precisely what I am motivated to do.
In this case I'm keeping myself at bay, waiting for the time to research this one properly, for those tangential benefits. But I will need to make time for it, which reinforces your point.
Get the programmer programming, and he or she will program. Make them stop to read, and many will fall away (or fall asleep).
As to solution, the only thing outside of the obvious would be perhaps to encourage the creation of a CPAN equivalent of a Tech Writer team; folks whose other CPAN documentation meets with widespread appeal and approval, and, like a Guild, could provide their services upon request of the module's maintainer.
I have no idea if this is even feasible; but it's the only thing I can think of at the moment.
In reply to Re: The problem of documenting complex modules.
by marinersk
in thread The problem of documenting complex modules.
by BrowserUk
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |