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

[SpecGL] C1: Define your terms, pcpl 1

From: Dominique HazaŽl-Massieux <dom@w3.org>
Date: Mon, 26 Jul 2004 15:47:47 +0200
To: www-qa-wg@w3.org
Message-Id: <1090849667.29618.134.camel@stratustier>
This would be the first principle, in section C1 of SpecGL.

I've another principle and 2 GP in the pipe. Comments and suggestions
welcome,

Dom
---------------
Principle: Define the terms used in the normative parts of the
specification

What does this mean?
The normative parts of a specification often uses technical terms in a
very restricted sense; write down the definitions behind these terms

Why care?
English (and other natural languages) are ambiguous, in so that a term
used in a given context can be interpreted differently in a different
context.  Interoperability between implementations can only be achieved
if implementors understand the the specification the same way; defining
the terms used in the normative parts ensures as much accuracy as
possible.
Also, once well-defined, the terms can be re-used in other
specifications.

Technique: 
1. use the same phrases to convey the same meaning: although repetition
is often seen as a stylistic error in prose, in a technical
specification, re-using the same phrases diminishes ambiguity, and
lowers the threshold of vocabulary needed to understand the
specification

2. review your conformance requirements/test assertions: the most
important terms to define in your specification are usually easy to
identify when reviewing conformance requirements or test assertions; for
instance, the subject of a conformance requirement is supposed to one of
the classes of product; the verb, one of the operations this class of
product can realize. 

Examples: The interoperability of the implementation of the CSS2 box
model has been problematic, due to the lack of definition of when a
<q>property is set</q> (see discussion on this topic
http://lists.w3.org/Archives/Public/www-style/2001Mar/0153.html )

-- 
Dominique HazaŽl-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org


Received on Monday, 26 July 2004 09:47:56 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:14:33 UTC