Good Specifications: Ernest Hermingway vs Leo Tolstoy
Mar 25, 2012How long should a good standard be? Just how many words should it have? Short Standards
A short standard is a good standard - every word the standard contains is a word that hundreds/thousands of implementers have to read. So keep it short - say only what needs to be said in order to get the standard to work, and don’t add spurious words.Write it like Ernest Hermingway, “known for his terse prose”.
But the problem with that is that there’s no way to know what is the minimum that needs to be said, and inevitably standards don’t say enough. As an implementer, I often read a standard, try and match it to my particular requirements, and wonder just how it’s supposed to work - there seems to be many different ways… if only they’d said more, there’d be less confusion.
Long Standards
An alternative approach is to say as much as you can when writing a standard. To clarify the usage of the standard completely and systematically. Every word the standard contains is a contribution to helping people understand it, and the more descriptive you can be, the more you help the implementers. These standards aspire to a Tolstoyan level: true epics, “thought to be one of the greatest novels ever written”… oh may they say that about our standards…
Except, of course, is that what they say about the long comprehensive standards is:
“x,000 pages? How on earth are we supposed to read that?”
and then the implementers don’t. Of course, when you give them a 50 page standard, they say that’s great, then later they say
“this standard is crap. How are we supposed to know what it means?”
Damned if you do, damned if you don’t.