Why You Hate Writing Documentation (and What I'm Doing About It)
Rocco Caputo will give a talk at YAPC::NA 2012 described as:
Documentation is anathema to hackers. Releasing early and often is much harder when every code change requires an editorial pass to an ever-growing body of documentation. The common solutions are to either not document anything, to let the documentation fall into disrepair, or to release late and not so often. What’s a fun-loving but conscientious hacker to do?
[From the YAPC::NA Blog.]
My little part in the greater Perl world.
"What’s a fun-loving but conscientious hacker to do?"
Focus your efforts on what's important. What's that, you may ask? The interface. Document the heck out of the interfaces, at all levels; the interface to the sub's, the interface to the modules, the interface to the classes. If the interface changes, change its documentation. If the interface is thoroughly documented, you can use the code without reading it.
Later, when the code is more stable, you can add the other documentation required by your QA's deforestation project.
Retraction. Rocco will no longer be able to make it to YAPC this year. This talk will be replaced with Interactive Data Analysis with Prima and PDL (http://act.yapcna.org/2012/talk/77)