Why is documentation the "castor oil" of programming?
Solution 1:
Health benefits
Both castor oil and documentation have many salubrious benefits.
See this Castor Oil Wikipedia entry; it is used:
- to help skin and hair
- as an additive
- as a laxative
With computers, documentation is used:
- to help users understand the program or application
- to clarify the workings of the program in the programmer's mind
- to explain the workings of the program in the understanding of newer team members
- to communicate to support staff the proper operation of the program or application
Punishment
Although it has health benefits, it is distasteful to many.
I was surprised to see that castor oil has been used as a punishment, especially by Mussolini's regime (op. cit.). It has been used by parents to punish children, at least according to the Looney Tunes that I watched as a child. The Wikipedia article confirms:
"Some parents punished children with a dose of castor oil."
"A heavy dose of castor oil could be used as a humiliating punishment for adults, especially political dissenters."
These lyrics from "The Perfect Nanny" describe an agreeable nanny:
Never be cross or cruel
Never give us castor oil or gruel
Source: genius.com
In that spirit, perhaps documentation could be seen as a punishment for programmers. Documentation may seen as a punishment because:
- It can be difficult for technical folk to express ideas in cogent, grammatical English.
- Documentation can be anathema to technical folk, for whom expressing concepts for a naive reader can be problematic. (In contrast, some live to express algorithms to a machine.)
- It requires the use of word processors (such as MS Word, which does not understand the subjunctive mood (one of its venial sins (don't get me started))).
- It requires editors, reviews, approvals, and often posting to a Version Control System.
- It has deadlines.
tl;dr
While castor oil and documentation are good for you, they will leave a bad taste in your mouth.