Draft Proposed Answer to Ian Hickson: Case of RFC2119 terms

Original comment (issue 1044 [1])

http://lists.w3.org/Archives/Public/www-qa/2005Jan/0009.html

 

Thank you for your comment, which the QA Working Group has accepted.  We
have reworded the affected section as you recommended and it now reads [2]

 

Requirement 07: Use a consistent style for conformance requirements and
explain how to distinguish them. 

"What does it mean? Specifications use different styles to convey
conformance requirements: RFC 2119 <http://www.ietf.org/rfc/rfc2119.txt>
[RFC2119 <http://www.w3.org/QA/Group/2005/02/qaframe-spec/#RFC2119#RFC2119>
] keywords, imperative voice, descriptive assertions, etc. Tell the readers
what styles are used, especially when the specification uses different
styles for different parts of the specification.

Why care? It is important for readers to be able to differentiate
requirements in the specification from non-requirements in order to either
implement or review them.

Techniques

Using RFC 2119 <http://www.ietf.org/rfc/rfc2119.txt>  [RFC2119
<http://www.w3.org/QA/Group/2005/02/qaframe-spec/#RFC2119#RFC2119> ]
Keywords (MUST, SHOULD, MAY, ...) makes it easy to spot conformance
requirements. According to the RFC itself, they should be used only to
establish <http://esw.w3.org/topic/RfcKeywords>  interoperation
[WIKI-RFC-KEYWORDS
<http://www.w3.org/QA/Group/2005/02/qaframe-spec/#WIKI-RFC-KEYWORDS#WIKI-RFC
-KEYWORDS> ]. They are usually written with distinctive formatting, such as
upper case or bold. It is a good idea to create a specific markup for them
too. It will be easier to extract conformance requirements and better for
accessibility (See  <http://www.w3.org/2001/06/manual/#RFC> The Manual of
Style: RFC 2119 Key Words [MANUAL-STYLE
<http://www.w3.org/QA/Group/2005/02/qaframe-spec/#MANUAL-STYLE#MANUAL-STYLE>
])."

 

 

 

[1] http://www.w3.org/Bugs/Public/show_bug.cgi?id=1044
<http://www.w3.org/Bugs/Public/show_bug.cgi?id=1044> 

[2]
http://www.w3.org/TR/2005/WD-qaframe-spec-20050428/#consistent-style-princip
le
<http://www.w3.org/TR/2005/WD-qaframe-spec-20050428/#consistent-style-princi
ple> 

 

 

Received on Friday, 29 April 2005 12:40:23 UTC