Learning about POD
Try perldoc perlpod for the POD man page.

Single point of documentation
Remember that single text documents tend to vanish leaving the new maintainer/developer unaware of all the hassle you went though. I'd write the POD into all the scripts and then copy the useful bits into a separate file. It's more work, but it'll be more useful to the next coder.

Documenting a large project
As to your last question. DON'T TOUCH THE CODE! Yes, documenting is a pain, and boring and I'm sure you can see 1001 ways to make the code a little clearer but if you're not being paid to fix the code and it's in production, don't touch it. It works (presumably), leave it alone.

Just go in, test away, work out what it does, try to guess how it does it, and document what you can understand. It's (probably) okay to put stuff like: 

##### Warning: through inspection, it appears that the
##### following code may fail under these circumstances:
# A) .....
# B) .....
# C) .....
##### A possible solution is in the following (untested) 
##### code:
# .........
# .........

[download]
but remember what you're being paid to do. Adding documentation to a program should never alter it's functionality. (Well, unless you're playing with Damian's selfgol).

If you feel that something really ought to be changed, write it down and bring it up with your supervisor after the documentation project has been completed. Don't allow yourself to be pressured into making functional changes at the same time as you're making formatting/documentation changes. Something will go wrong and your documentation will get blamed.

Oh, and use CVS. Or some other revision control system. And check your changes in regularly, although probably on a code branch and not directly into the main tree.

Lastly:
Good luck!

Hope it helps.

jarich

In reply to Re: Crash Course in POD by jarich
in thread Crash Course in POD by jens

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.