- From: Lynne Rosenthal <lynne.rosenthal@nist.gov>
- Date: Tue, 03 Aug 2004 08:51:14 -0400
- To: Dominique Hazaël-Massieux <dom@w3.org>, <www-qa-wg@w3.org>
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