Beware the Bad Spec........
I’ve recently been having an Email conversation with some the guys who wrote the technical specification RFC3920 about the language used and it’s left me wondering how many more times I will see the same mistake made.
Specifications are suppose to aide clarity, they’re suppose to make it easy to produce compatible systems because a good specification will leave little room for ambiguity, but the big problem is the eagerness of specification writers to either make up terms or redefine words to fit their needs.
The case in point with RFC3920 is where it talks about things called “XML stanzas”. I’ve been writing software for nearly two decades now and I have never seen this term, so I went to a dictionary which told me a stanza is;
I expect many of you are in the same position I was and you’re thinking “XML part of a poem?, that doesn’t make sense.”. Well, that isn’t the definition that’s been “adopted” by the specification writers, they’ve taken it upon themselves to define an XML stanza as a segment of an XML message (which many people would call an XML chunk).
Information technology is a difficult thing to discuss and many terms exist to define complex pieces of technology or ideas in a single word, but when specification writers start making up new terms for things which have already have names they start raising the barrier of entry for someone wanting to use the specification which goes against the reason the specification exists in the first place.
So if you’re a specification writer and you’re not sure what to call something go to Google for a while and see if there already exists a name, and if you’re someone who has to read specs and you see a new term, maybe, after you know what the term means, you ask the question “Hasn’t someone already got a name for this?”, and if they haven’t, then you probably looking at something unique and very interesting.