People without senses of humors always deny it. And if you work in a company where people will respect you less because your specs are breezy, funny, and enjoyable to read, then go find another company to work for , because life is just too damn short to spend your daylight hours in such a stern and miserable place. Here's why I think that programmers have trouble writing good specs. When you write code , your primary audience is the compiler . Yeah, I know, people have to read code, too, but it's generally very hard for them .
Programmers often try to write specs which look like dense academic papers.
One of the big differences between computers and human brains is that computers are willing to sit there patiently while you define the terms that you want to use later. But humans won't understand what you're talking about unless you motivate it first. Humans don't want to have to decode something, they just want to read it in order and understand it. For humans, you have to provide the big picture and then fill in the details. With computer programs, you start at the top and work your way to the bottom, with full details throughout.