How systems were all too often documented in the 60s and 70s
Upvoted, but you missed something: the system design documentation is equally important (1), particularly if, as was common, the program code was uncommented and/or the 'system designer' decreed that some utterly incomprehensible and uninformative scheme for naming variables, paragraphs and sections must be used (2).
The end result was that often the only surviving system documentation was the program source code and puzzling out what the system actually did from the code could be very difficult indeed.
(1) System design documentation was typically hand written, held in ring binders and NEVER updated. Since any documentation of bug fixes or system enhancements was generally discarded when the job was done, or had never existed, what documentation still existed was soon utterly out of date and, consequently, was frequently binned whenever the design office shelves got full. The most extreme case of this I ever saw was at Smiths Industries in Cricklewood, where the System Analysts were kept as isolated as possible from the programing teams and had a policy of immediately scrapping all documentation once the system or patch had successfully gone live. This sort of shambles persisted until PCs and word processing became common in the late '80s. The first purpose-designed system documentation system I met was ICL's Advanced Data Dictionary, which was around on VME/B systems in the late '80s.
(2) The worst example I ever saw was in an accounting package the ICL bureau I was working in mistakenly bought around 1970. It had a coding standard, but it was this:
- data names were all of the form XX99 regardless of their level or usage, so you saw things like this
FD CR01.
01 CR02.
05 CR03 PIC X(15).
05 CR04 PIC S9(6).99 DISPLAY.
..... as a continuous sequence right through all the various card images the program could handle. Then you got to the records on mag tape, which started from MT01 and continued through all records in the various different tape files, started again from LP01 for printed output and - you guessed it - started again from WS01 for all working storage.
- in PROCEDURE DIVISION, use of SECTIONS was forbidden and all labels had to be 5 digit numbers. They weren't even in numeric sequence and, guess what - there were no comments in the entire set of programs. IOW, just what causes this MOVE to be executed, what is it trying to achieve and what will the program do next:
IF CR08 > WS11 MOVE CR15 TO WS23 GO TO 23500.
The bureau wasted a heap of money buying that junk because it was utterly unmaintainable. I never heard whether they got their money back: all I know is that I designed and wrote a replacement using structured and meaningful names and that it was still in use and well regarded when I visited 4 years later - not bad, seeing that in the 70s that sort of system was designed for a life of around 3+ years.
In summary, thanks to this sort of nonsense, why should there be any surprise that the old COBOL systems are still in use?
They can't be replaced simply because nobody knows exactly what they do or how they do it and the cost of going through badly written, uncommented and undocumented code is prohibitive.
As a more current comment, one of the really good things about Java is the javadocs utility. This generates nicely formatted HTML pages from the class and method level comments in source files. So, in principle, the system designers could deliver low-level design as a set of Java pages containing class and method level comments together with method skeletons and the documentation would be up to date because developers would update the comments as they modify the code. Sadly, however, judging by the standard of documentation I see in 3rd party Java packages, yer average developer today still can't be arsed to adequately document what he writes.
