Re: [SpecGL] C1: Define your terms, pcpl 1

Only a few minor comments and 1 question.  I think this nicely captures 
what we want to say.

Do we only care about defining the terms in the normative 
parts?  Hmm.  (thinking out loud with via typing)  I think we want all 
terms defined, but this is the critical piece.  I think that editors will 
see this and will end up following this Principle for informative terms as 
well.  So, in the spirit of keeping things simple and direct, this 
Principle is fine by me.

>---------------
>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

s/in so that/ such that

>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
suggest; if implementors have the same understanding of the specification;
s/the the/the

>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.

excellent point.

>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.

I don't understand the for instance.....

>Examples: The interoperability of the implementation of the CSS2 box
>model has been problematic, due to the lack of definition of when a

/of definition of/of a definition for/

><q>property is set</q> (see discussion on this topic
>http://lists.w3.org/Archives/Public/www-style/2001Mar/0153.html )

Received on Monday, 26 July 2004 19:16:48 UTC