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

[SpecGL Draft] A.1 GP In the conformance clause, define how normative language is expressed.

From: Karl Dubost <karl@w3.org>
Date: Thu, 5 Aug 2004 15:04:30 -0400
Message-Id: <4777C44C-E712-11D8-91B3-000A95718F82@w3.org>
To: www-qa-wg@w3.org
Good Practice:
	In the conformance clause, define how normative language is expressed.

What does it mean?
	There are a number of common language styles for expressing the 
detailed conformance requirements of a specification. One of the most 
popular is RFC 2119 [RFC 2119] -- keywords like must, may, and should 
not both signal the presence of conformance requirements and express 
their relative mandatory nature. Other styles include imperative voice 
statements (as in the statement of the Good Practice item), physical 
segregation via styling, labelling, etc. What matters is that the style 
be consistent, unambiguous, and (ideally) quickly recognized.

Why should I Care?
	A specification is composed from many mandatory parts. Some 
requirements with a programmatic nature, for instance DTD and XML 
Schemas for a markup language, are easy to recognize and so to 
implement. Most of the time, these strict definitions of a language are 
not enough and there is a need for an explicit prose to explain the 
nature of a name token (element, attribute, feature). A clear 
definition of the normative language helps developers to know the 
requirements, to create test assertions for test suite developpers, and 
to avoid ambiguities when debating the prescriptive nature of the 
prose.

Related:
	Link to Test assertions.
	Link to RFC 2119
	See @@section C.3@@.

Techniques:
	1. Choose a formalism to express requirements
	2. Create a test assertions list
	3. If you can't express without ambiguities a test assertion, it means 
that you need to write again in your chosen formalism or you need to 
add requirements for your normative language that will cover these 
cases.
	4. Don't use normative language which makes the interpretation vague. 
(For example, MUST assume)

Example:
	Plenty of examples for RFC2119.
	I will find examples for other kind of languages. This document and 
Web Arch for example


-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***

Received on Thursday, 5 August 2004 17:56:22 GMT

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