interrogativus

On a recent nostalgia trip for my first computer and first GUI, I encountered the following example of user-hostile documentation:

Documentation quality varies from good to unclear and insulting: “The Becker BASIC system will help you to learn structured programming: After about the 15th or 20th error message, you’ll learn to be much more careful in your program development.” – BeckerBASIC review

The reviewer interpreted this line as being unclear and insulting… although out of context, it is hard to tell if this characterization is an exaggeration (the manual writer was trying to be humorous, not antagonistic, I think). It is hard to imagine such a line appearing in a serious commercial software product’s documentation today (from Microsoft or Oracle or Sun, for example).  More likely, perhaps, in an open-source project or an indie development shop whose brand attributes include “edgy” or “attitude”.

Still, if we were to slavishly follow the maxim: “the manual (documentation) is the oracle”, would we be trying to test that the software produces a sufficient number of error messages on poorly structured code?

I think this is the solution to the puzzle I posed earlier (here and at the CAST 24×7 website): a requirement that is intended to be understood as humorous and therefore only a “requirements jerk” would produce the test case: “create a program with terrible spaghetti code. Expected result: 15-20 errors generated, programmer learns about structured programming.”