[Cryptography] Readable manuals, and fixing bugs by documenting them

[Bob Wilson]

Just a couple of old-fogie thoughts... (These points came up in 
different threads, so saying "Re..." doesn't really work well.

One of the bad things for manual construction was the development of 
documentation software. For this purpose I include everything from word 
processors through the various roffs and the like. I was working in an 
industrial setting at the time when management began to notice those. 
There had been on the staff editors and other people who new some 
grammar and diction, with all manuals having to pass through their 
hands. An extra step costing money... So documentation reverted to those 
of us producing the product to be documented. The quality of 
documentation we supplied plummeted. Technical education and experience 
don't necessarily imply ability in using natural language or describing 
how to do something. (We've probably all had teachers who were world 
experts in their fields but could not explain anything...) So one reason 
those great manuals disappeared is that the people who wrote them 
disappeared first.

And some bugs have to be documented but must not be "fixed". Another 
place where I worked was bringing out a line of minicomputers (that will 
let you date this...) that were to be sold as an upgrade path from 
machines another company built, so that our boxes would run the same 
code but do it faster, with looser constraints on sizes, etc. Fine idea, 
but the boxes we were emulating (including their OS and many 
applications) were not bug free, and we found some customer had built 
their applications relying on some of the bugs. We were seriously told 
we had to go for "bug level compatibility". But of course other 
customers had to get documentation that told what the system really 
would do.

Bob Wilson