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

Very timely - I'm going to extract some of this for a discussion I'm having 
with the healthcare community (HL7 electronic health records) on how to 
indicate requirements in their standard.

Comments are on grammar.

At 04:56 AM 8/3/2004, Dominique Hazaël-Massieux wrote:
>(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)

Yes. For now, its better to have duplication and we can merge it later.

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

Suggest:  It's important for specification readers to be able to 
differentiate requirements in the specification from non-requirements in 
order to either implement or review them.


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

Split.  Make new sentence after the ;

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

/use/uses
It is often used in guidelines or speculations that need readers' involvement.
The default is that it doesn't necessarily.
(new sentence) Additionally, the use of the imperative voice may make 
translation to some languages more difficult.


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


--lynne

Received on Tuesday, 3 August 2004 08:51:18 UTC