|Syntactic Confectionery Delight|
Crash Course in PODby jens (Pilgrim)
|on Sep 25, 2002 at 00:29 UTC||Need Help??|
jens has asked for the
wisdom of the Perl Monks concerning the following question:
I've just been contracted for a few weeks (or more) to document a messy 20,000 lines of Perl code. The code base itself, by the sounds of it, is a hack on a hack on a hack on a prototype that never got thrown away. Worse, the programmer who's been maintaing and extending it for the last year or so is Chinese and speaks/writes English poorly, meaning that the existing documentation isn't very useful.
Thus, the need for documentation.
The question: I've never used POD before. But I suspect that's the best way to approach this--POD everything and then accumulate that into a Programmer's Manual. I've tried 'perldoc perldoc' but that wasn't very helpful--where can I find out more about creating POD? Also, there's several dozen scripts, each of which could have it's own perldoc--but it's probably better to merge them all into a single text document. How do I do this?
the other question: This is, in a way, the documentation project from hell. Does anyone else have similar experiences with documentating big chunks of messy, obfu codes years after it's been written--and when it's in production?
Any thoughts on this would be much appreciated.
Microsoft delendum est.