2006-02-18 06:09 UTC Writing specifications: Kinds of statements
When I read or write a document that is to describe how multiple independently-produced products are to interact — that is, when I read or write a specification — I try to classify all the statements in that document into these three categories:
- Normative conformance requirement statements
- Definitions
- Informative statements and descriptions
A "statement" is a sentence, a diagrams, a code fragment, or some other small unit.
In more detail:
- Normative conformance requirement statements
-
These are also known as conformance criteria. A normative conformance requirement statement is one that uses RFC2119 terminology to make a requirement on the products in question.
Normative conformance requirement statements are key to a specification, and are the only type of statement that you can't do without. They say how the products have to act, and are the whole point of having a specification in the first place. Conformance criteria are what distinguish a specification from a tutorial.
A conformance requirement must be testable. That is, you must be able to tell whether a product follows it or not. If you can't tell if a product follows it, then it isn't a conformance requirement, and shouldn't pretend to be one.
A conformance requirement must also be clear (either by context or explicitly) about exactly what kind of product it applies to. There are typically four kinds of products that are affected by a specification:
- Creators (e.g. Web page editors)
- Content (e.g. Web pages)
- Processors (e.g. Web browsers)
- Conformance checkers (e.g. validators)
Obviously, a requirement for one does not necessarily apply to another. Less obviously, this means you have to be very careful in how you phrase things.
Here's an example of a well-written conformance requirement (from the XForms specification):
The XForms Processor must ignore any foreign-namespaced attributes that are unrecognized
It is easy to test: if you include a bogus foreign-namespaced attribute and something happens differently, then the requirement is being violated.
It is clear about what it applies to: it explicitly says that it applies to XForms Processors.
This last point also means that it doesn't say anything about whether documents are allowed to include any foreign-namespaced attributes. This is in fact a good thing; the XForms specification has other conformance criteria explicitly aimed at documents to cover that question.
Note, also, that the sentence on its own doesn't really mean much: it uses lots of terms that are defined elsewhere in the same specification. That's fine, and is where the "definitions" kind of statement comes in.
- Definitions
-
Definitions are statements that make it easier to make normative conformance criteria without being overly verbose. They are the spec-writing equivalent of function definitions or macros.
Here's an example of a definition:
- XForms Processor
- [Definition: A software application or program that implements and conforms to the XForms specification.]
In well-written specifications, one should be able to take all the terms used, replace them by their definitions, and not change the meaning of the specification.
For example, you could take the definition above and place it into the normative conformance criteria in the previous section to get:
The software application or program that implements and conforms to the XForms specification must ignore any foreign-namespaced attributes that are unrecognized
The meaning is exactly the same, it's just more long-winded.
- Informative descriptions
-
The third kind of statement in a specification is the informative description. These are statements that don't actually affect the meaning of the specification but help readers understand what is going on.
There are various kinds of informative statements:
- Notes and asides
-
Notes and asides: informative statements or suggestions that aren't part of the main text. These are often used to explain the reasoning behind more obscure parts of the specification. An example:
Note: Foreign-namespaced attributes are allowed on element
submission, but no behavior is defined by XForms 1.0.Exactly what is a note depends on what the specification says is a note. Specifications usually have a section that describes typographic conventions that explain this.
- Examples
-
Examples are a key component of any specification, in terms of making it more accessible to readers. They provide one with a guide as to what the prose is attempting to say. Examples, however, are not provide normative conformance statements: they are merely informative. Never use an example to determine exactly what the specification says: only use the definitions and the conformance criteria. If the example seems to contradict the normative prose, the example is probably wrong. It happens more often than you might imagine!
- Statements of fact
-
Well-written specifications will often include statements of fact that are effectively repeating or summarising definitions or conformance statements found elsewhere in the specification, making it easier to understand the specification.
An example:
Within the containing document, these structural elements are typically not rendered.
It is very easy to confuse statements of fact with normative conformance criteria, because they are often phrased similarly, are styled the same, and usually appear right along with conformance criteria.
In specifications that use RFC2119 terminology, the key to distinguishing statements of fact from conformance criteria is to check to see if the spec uses any of the RFC2119 key words. If it doesn't, it isn't a normative conformance statement, and is either a definition or a statement of fact. It's a definition if it defines a specific term (either explicitly, as in the quote above, or implicitly, using the construct "a term is definition"). Otherwise, it's just an statement of fact.
Statements of fact can sometimes be incorrect. If a statement with no RFC2119 terms contradicts a conformance statement (one with RFC2119 terms), then the former is incorrect. It doesn't change what the specification is saying. (It makes it a poorly written, confusing, specification, but doesn't change what implementations have to do to conform to it.)
- Diagrams
-
In most specifications, diagrams are explicitly called out as being informative (non-normative) descriptions.
In any case, you should be able to remove all the informative statements from the specification, leaving only the normative conformance criteria and the definitions upon which the conformance criteria rely, and not in any way change the meaning of the specification.
Try to classify sentences in specifications you read or write into these categories, and see if it helps you understand what the spec is really saying.
If you spot anything in specifications that I'm writing which doesn't fall into these three categories, let me know!