I'm in the final phases of a project that has been going on for some time. We have extensive documentation in all modules and scripts and several POD files filled with details and overviews of various sections and how the pieces fit together (141 pages of HTML with indeces, and nicely linked together).
Now we are getting ready to hand the code over to the $client's internal developers and we have asked them to peruse the docs to let us know if there is anything lacking. They (actually just one person) gave us a list of several things (most of which were there so it makes me think they didn't even look at it) that they want, most notably flow charts that show every control module (we're using MVC), every run mode (using CGI::Application), every template and every hyperlink (or form submission) between them.
I have a problem with this. Flowcharts are nice when used to gather requirements but quickly become stale if you do any kind of iterative development and I hate maintaining documentation that is separate from code. So I've been pushing back on this.
As it just happens I've been reading "The Mythical Man-Month" and just came across a great section on flowcharts. (written by Frederick P. Brooks, JR. in 1975)
The detailed blow-by-blow flow chart, however, is an obsolete nuisance, suitable only for initiating beginners into algorithmic thinking.
I think this universal experience is not an embarrassing and deplorable departure from good practice, to be ackknowledged only with a nervous laugh. Instead it is the application of good judgement, and it it teaches us something about the utility of flow charts.
...
A basic principle of data processing teaches the folly of trying to maintain independent files in synchronism...Yet our practice in programming documentation violates our own teaching.
