http://qs321.pair.com?node_id=119663


in reply to How to write documentation?

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..
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