I used to like the idea of having voluminous documentation for projects until I started working for a while and found that after the initial scan to get an idea of what was supposed to be going on in the program I relied almost exclusively on the code, the comments contained in the code and such accurate descriptions of data structures and protocols that were extant or could be created on the fly. I've grown increasingly impatient with large external (to the code) documentation requirements since they are so hard to keep current with the codebase. (And I have spent many a long night trying to track down why something I was doing was blowing up on me only to find that I was relying on outdated or inaccurate documentation.) With systems (or languages, or programs, or whatever) that I use over a period of time I find myself looking only at the most technical material to find out very specific details, and as far as graphical aids are concerned you might consider that tables of information are very informative.

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

In reply to Re: Algorithm, Flowchart and Refactoring by scholar
in thread Algorithm, Flowchart and Refactoring by artist

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.