You're falling victim to a common fantasy: that maintenance programmers will read great works of documentation before they set about making changes. In 20+ years in the business, I have rarely seen this happen. Instead, the best you can hope for is the equivalent of a quick glance at a map before hopping into the car, with occassional checking of the map along the way.

So go graphical, and give people something they can assimilate quickly. I like UML sequence diagrams for giving me a quick understanding of flow, and some form of class diagram to give me some idea how things are constructed. An occassional State chart is also an effective way of communicating what your program is doing.

Martin Fowler's UML Distilled is a excellent (and short) introduction to UML.

Random thoughts...

I always think of my test suite as one of my prime sources of documentation. If you've not already got one, write one. Especially since you can't really refactor with any confidence without one.

Personally, I put a good test suite above any other sort of documentation - so I'd do that first (if not already done).

As for "standard languages" UML is probably your best bet. The various UML diagram types probably cover all that you need. The basic state & class diagrams will probably be enough for you.

However, if you're going to be refactoring your code base it doesn't sound like it's going to be worth documenting structures that you are going to change.

If you're writing documentation for "perl" people - consider using POD. It's a nice simple format, and the fact that its usually in close proximity to the code means that it tends to be updated and accurate.

Developing a DFD really makes you thing about your processes and your information sources and sinks, plus it's a picture that can quickly convey a lot of information to someone who won't spend much time reading documentation.

Cheers!

Brent

-- Yeah, I'm a Delt.

jdporter
The 6th Rule of Perl Club is -- There is no Rule #6.

1. Gather up all your requirements and organize them. Sift through them and try and make them less "organic" and more "holistic".
2. Once you've got that done, then build a design from those requirements. (Note that you might end up with a design radically from your current implementation. This is ok, but something to note.)
3. Make note of those things that differ between your design and your current implementation. Those are now RFC's.
4. As you complete changes in a section, make sure to update the use-case (or design) associated with that section.
5. Last, but not least, write self-documenting, strongly-cohesive, loosely-coupled code. You should want to refer to the code if you want to find out what the code does. Refer to the documentation if you want to find out what problems the code is intended to solve.

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

A long-time favourite way of diagraming the logic and flow of both problems before coding, and the code as an after-the-fact process is little known (and old *) technique called Warnier-Orr diagrams.

Personally, I find them infinitely preferable to UML. They are less complex and much easier to draw, read and understand IMO, but YMMV. There not perfect by any means, but little is.

* I first saw them described in a series of Byte magazine articles when I was a student. I just did a google and discovered these were in December 1977 and January 1978! {sigh} How time flies when your having fun.

That said, the very first time I look at a new system the introductory information even when a little bit out of date is invaluable in providing a road-map of sorts to let me know where I have to look to find out those specific details. I have used data flow diagrams for years and find them not only very flexible, and helpful in keeping a large flow structure in my head but also something that are easily explained to non-programmers and can be useful in delineating the choices that management might have to make in business rules / policy down the road. They are rather equally descriptive of batch, interactive or real-time sorts of processes at least at the higher levels, though they can be a little dicey sometimes with OO systems. I almost never take the DFD (or the data dictionary or the event table) down much past one or two levels so it is also something that I can put together fairly quickly and keep current with little effort relative to that put into coding or refactoring.

It sounds like you have a system that is important to your company but not life-critical so with that in mind: Having seen this recommended many times I know it's not something that only I do but of course YMMV. I would start by thoroughly describing all the data structures, file formats, protocols, and unusual parameter-passing conventions. If the flow was fairly complex I might also put together a DFD or whatever similar graphical aid would be most useful to your colleagues. Step back and take stock of what that looks like and it should be pretty clear where additional explanations are indicated. Add a little descriptive or introductory information at a time and try to get someone unfamiliar with the program to review it and tell you if they think they could maintain it with what you have. Then stop. :)

(DeMarco, Structured Analysis and System Specification is the classic text on DFD's. Yourdon, Modern Structured Analysis takes the idea a little further.)

I also like to refactor it so that the logical flow of the program could be modified and makes it easy for future improvement.

One of the points of refactoring is to make the code more readible, so that documentation is not needed within the code itself. I have to agree with DWS regarding documenting for maintanence programmers. It is not worth your time. For most developers, it is simply more efficient to document the API of module so that other programmers can use it. But for maintanence, it is better to have clear code than volumes of documentation.