in reply to Algorithm, Flowchart and Refactoring
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.)
|
|---|