W3C home > Mailing lists > Public > www-qa-wg@w3.org > August 2004

[SpecGL] C2: Identify what is required, Pcp 1

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 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.30 : Thursday, 9 June 2005 12:13:17 GMT