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

At 01:28 PM 8/6/2004 -0400, Lynne Rosenthal wrote:

>Reading this and rereading C2, GP1 - I think that we can delete this, they 
>are redundant.  In C2, GP1 where it says to tell the reader what style is 
>being used, we amend that to say, tell the
>reader and put it in the conformance clause.

This was discussed and done on purpose -- put the most fundamental and 
important stuff up front, even if it overlapped stuff further into the 
body.  That in turn followed from refining your original outline into draft 
text.

It is explained in SpecLite FPWD [1]:
"The scope of content in a good conformance clause overlaps most of the 
other remaining topics in these specification guidelines. Possible 
repetition notwithstanding, a handful of points -- conformance clause Good 
Practices -- are worth mentioning here up front."

I don't mind if we address and change that decision, but I'm concerned that 
we're not doing that explicitly, rather we're erasing it with a series of 
small editorial steps.

-Lofton.

[1] http://www.w3.org/TR/2004/WD-qaframe-spec-20040602/#conformance-clause


>--lynne
>
>
>At 04:45 AM 8/6/2004, Dominique Hazaël-Massieux wrote:
>>Le jeu 05/08/2004 à 21:04, Karl Dubost a écrit :
>> > Good Practice:
>> >       In the conformance clause, define how normative language is 
>> expressed.
>>
>>I haven't looked into the details, but as I mentioned before, this needs
>>to be coordinated closely with C2, GP1:
>>http://lists.w3.org/Archives/Public/www-qa-wg/2004Aug/0002.html
>>
>> > 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,
>>
>>s/labelling/labeling /
>>
>>I think this part should link to C2 where the different styles are
>>explained in more details.
>>
>> >  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).
>>
>>s/nature of a name token/semantics attached to the syntax tokens/
>>
>> >  A clear
>> > definition of the normative language helps developers to know the
>> > requirements, to create test assertions for test suite developpers,
>>
>>s/developpers/developers/
>>
>> >  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@@.
>>
>>(C.2 now)
>>
>> > Techniques:
>> >       1. Choose a formalism to express requirements
>> >       2. Create a test assertions list
>>
>>Hmm... Creating a test assertions list simply to "define how normative
>>language is expressed" (the GP we're under) seems like a real overkill;
>>I think you should scrap 2, and say in 3 "try and express the
>>conformance requirements as test assertions; if you can't expres..."
>>
>> >       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)
>>
>>I think it would be worth explaining a bit more what you mean here; I
>>think I understand, but I don't think most people not knowing our
>>background would.
>>
>> > Example:
>> >       Plenty of examples for RFC2119.
>> >       I will find examples for other kind of languages. This document and
>> > Web Arch for example
>>
>>I suggest these examples should be added to C2 instead; this GP is
>>really about putting information in the conformance section rather than
>>about the information itself.
>>
>>Dom
>>--
>>Dominique Hazaël-Massieux - http://www.w3.org/People/Dom/
>>W3C/ERCIM
>>mailto:dom@w3.org
>