- From: Dominique Hazaël-Massieux <dom@w3.org>
- Date: Tue, 03 Aug 2004 10:56:54 +0200
- To: www-qa-wg@w3.org
- Message-Id: <1091523414.1416.122.camel@stratustier>
(old section C2 "Identify normative and informative parts" can be removed, since the topic is already addressed in section A2, so the old section C3 is now C2; I think this proposal is more complete than the GP in section A1, but I don't know how we should handle having both in SpecGL) Principle: Use a consistent style for conformance requirements and explain how to distinguish them What does this mean? Different styles are used across specifications to convey conformance requirements: RFC 2119 keywords, imperative voice, descriptive assertions, ... Stick to one type of style, and tell your readers which style is used in the text. Why care? It's important for the reader of the specification to be able to know where are the actual requirements set by the specification, either to review it or to implement it. Technique: * using RFC 2119 Keywords (MUST, SHOULD, MAY, ...) makes it easy to spot conformance requirements, due to their specific uppercase formatting; according to the RFC itself, they should be used only to establish interoperability (see wiki discussion http://esw.w3.org/topic/RfcKeywords); a good conformance requirement using RFC Keyword is of the form: <subect> <rfc_keyword> <operation>, where <subject> is one of the classes of product, <rfc_keyword> one of MUST, SHOULD, MAY, and <operation> a verb describing one of the operations the classes of product can do (e.g. "send a message", "process a request") * the descriptive style takes a different approach: it describe the semantics of the language, rather than how it must be handled; the benefits of this approach is that it allows a wider reuse of the said semantics, but at the cost of not defining a common behavior between implementations, which may lead to interoperability issues (see also the wiki discussion on Meaning vs Behavior, http://esw.w3.org/topic/MeaningVsBehavior) * the imperative style use the imperative form to convey the requirement; it is often used in guidelines or specifications that needs readers involvement. Its defaults are that it doesn't necessarily make clear *what* needs to conform (since there is no subject), and the use of the imperative voice may make it harder to translate in some languages Using one of these styles doesn't preclude using another one in a different part of the specification as long as this is made very clear to the user. For instance, when defining a language, it is a good idea to define first its semantics using the descriptive style, and then the behavior of one (or more) type of implementations using RFC Keywords. See for instance the SVG 1.1 (http://www.w3.org/TR/2003/REC-SVG11-20030114/) Recommendation, where the semantics are defined in descriptive style, and the implementations requirements with RFC Keywords (http://www.w3.org/TR/SVG11/conform.html) -- Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/ W3C/ERCIM mailto:dom@w3.org
Received on Tuesday, 3 August 2004 04:57:13 UTC