This note is a little motherhood and apple pie about how a specification should be couched so as to clearly add a new well-defined piece to the technology.
A technical specification defines something. The document must specify the thing being defined as well as give its definition: a "left hand side" as well as a "right hand side". Both must be done quite precisely.
Typically, technical specifications for the web specify a language or a protocol. A protocol is a language for messages, plus a set of constraints on the sequence of messages. A language is a set of symbols, the syntactic constraints on the way their are combined, and the semantics of what they "mean" at some (possibly more than one) level. (See also Meaning of web documents)
The test of a good specification is that it clearly defines what implementation (document, message, program) conforms, and of course that it ensures by its design that whatever conforms works to provides the required function.
The document should state what sort of things is being defined. It should introduce a new term which characterizes that which conforms to the specification. Examples of a conformance term could be
The same specification document can define more than one term. such as a "strictly conforming WWidget" and a "loosely conforming WWidget" but one should beware of diluting the "WWidget" brand.
As systems become more self-describing, the term is given a formal identifier. Examples could be
In this case where a MIME type or namespace has an identifier, then this is obviously the crucial term to use to be unambiguous.
Wherever possible, conformance phrases will be grounded in the Web: identified by a URI.
More has already been written on this, and most of it seems to be in consensus in the W3C.
It is important to remember what you are defining as you write the text. For example, if you are defining a "foo-valid document" then using "is invalid" in the text can be assumed to apply to this but "is incorrect" or "is wrong" or "produces an error" does not unless the language is explicitly linked to the conformance term.
A good spec similarly pays attention to:
When defining a language, whenever possible specify directly the meaning rather than the sort of thing you would expect some software to do with it. Typical behaviors of an agent may be very useful to explain the intent non-normatively.
For example,
"x" indicated that the check is void
is better than
"x" indicates that the check should be rejected with a fatal error.
You can tell people what something means, you can't tell them what to do about it, unless you are defining a protocol. When defining a protocol, then the constraints should ideally be given as a state transition diagram or table to make them totally clear.
When defining a message which in fact binds to human social entities, then this must be clear. You could end up in court explaining it if not. ("The MMTP protocol defines the meaning of a message sent by or on behalf of a party herein referred to as the "debtor" to a party referred to as the "creditor". The creditor is identified by the foo-email-address...)
When defining a part of a specification deliberately to be similar to another specification,
A few examples of things to ask about a spec -- though generalization is difficult.
So much for another bit of folklore. Comments, suggestions welcome.
Tim BLS. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP0041
These are some of the raw bits of standards which I picked up from Peggie Rimmer at CERN, and from working with IEEE, IETF and W3C specifications over the years. I am sure others have written books on it. Comments, suggestions welcome
Last change $Id: blank.html,v 1.1 1999/05/24 14:24:19 timbl Exp $
Tim BL