Sounds like you've got a good start to the documentation in writing the POD documentation for each program your write..
There are a few things I usually do that mean if something happens to me, then everything is maintainable..

• First comes the POD, to allow a man-page like overview of the functionality of the script. Anyone reading this is assumed to be technically literate, and likely to either be reverse engineering your whole system or developing it further.
• Next comes the internal comments to the code. I always have the functions seperated from the rest of the code quite visibly. Each of the functions is domment described as to what arguments it expects, what it does, and what it returns. This means anyone skimming through your code can treat functions as 'black boxes'.. This greatly speeds someone's understanding of just what your code does.
• Next comes the 'HOWTO'. This is a rough guide to the dataflow of the system. What datasources you have, and what datasinks. What programs do what, and why. Also, where you keep things like temp files, and any bits that may need cleaning in case of serious system failure... Basically, this is a guide to keeping things working without having to know just what the system is doing.. It's there to give someone time to understand the true intricacies.
  
• As time goes on, it's a good move to have a proper user guide on the go. This should be a detailed version of the 'HOWTO' dealing with all the data munging that you perform, how the seperate scripts interact, examples, and just about everything you can think of to detail the system.

As, in my current job, I've taken over a system coded by many people in many languages (C, Perl, Bash, Csh etc), all with little to no documentation, I think that the biggest problems I had were lack of any HOWTO, or overview of what the system was doing, where it threw temp files, what it could and couldn't handle, and which scripts dealt with which area (no, there was no distinct bin dir.. All the code was spread across about 20 different bin dirs, most not obvious).
This meant that I had to read each script (again, not documented), and work out each function (if it was even split into functions). Needless to say, it was a painful task.
So, in order of importance, I'd say it would have to be:

1. A generic HOWTO to enable a random technical person, with skills in Perl/Apache to keep the system alive, and give them a few pointers to maintenance without going too much into specifics. This will at least give them time to lear the system without the world falling apart around theirs ears.
2. The POD documentation. This is a wonderful aid to letting people get a good view of what the system as a whole is really doing, and learn it rapidly.
3. The internal comments. This is great to allow people to use your internal APIs you develop, and re-use your code when they develop later.
4. The in depth user manual is the icing on the cake that walks people through everything... It's good to have, but, without having the above steps complete, it'll likely be lacking in vital areas, that usually get picked on when you do the above docs.

When you ask what keep me going on in this project I inherited?? Well, lots of caffeine and bloody mindedness spring to mind.
The parts I've re-written all follow the steps I've mentioned above, and what took me weeks to work out, reading the source, I've had others picking up in hours reading my docs. Which is exactly what I've been aiming for.

The last stage, after I get all the above done, is a little more light-hearted.. I take to wearing a teeshirt with the big letters "RTFM" on it.. Then I get back to doing the next thing, without having to spend more time away from my code fielding answers that are already in the documentation now. :)

Hope this helped some,

Malk

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.