More thoughts on 'you can'

[Patrick Durusau <Patrick.Durusau@sbl-site.org>]

Greetings,

Another aspect of the 'you can' discussion is whether it is being used 
to state a requirement.

Note that in section 1.2 Notation, we limit key words to those found in 
RFC 2119. http://www.ietf.org/rfc/rfc2119.txt

"Within this specification, the key words "must", "must not", 
"required", "shall", "shall not", "should", "should not", "recommended", 
"may", and "optional" are to be interpreted as described in [RFC2119] if 
they appear in uppercase bold letters."

Another relevant document on practice is "QA Framework: Specification 
Guidelines," http://www.w3.org/TR/qaframe-spec/, see section C.2 in 
particular.

Note that the "QA Framework: Specification Guidelines" does have one 
example of 'you can' but it is not stating a requirement. It is 
directing the reader to additional information, not stating a requirement.

For example, in 2.8, Page Styles and Layouts, fifth paragraph, the first 
sentence reads:

"In text and spreadsheet documents, you can assign a master page to 
paragraph and table styles using a style:master-page-name attribute."

If that is stating a requirement of the specification, then it is not 
using the terms specified in 1.2 Notation.

Restated using 1.2 Notation:

"In text and spreadsheet documents, a master page MAY be assigned to 
paragraph and table styles. Master page assignments to paragraph or 
table styles are made using the style:master-page-name attribute."

Another source to consider would be to post the question with a couple 
of examples to more experienced standards writers. I suspect Jon Bosak 
has participated in writing more standards than I have read so he or 
others with his experience might be good sources of advice on this type 
of style question.

Hope everyone is having a great day!

Patrick

-- 
Patrick Durusau
Director of Research and Development
Society of Biblical Literature
Patrick.Durusau@sbl-site.org
Chair, V1 - Text Processing: Office and Publishing Systems Interface
Co-Editor, ISO 13250, Topic Maps -- Reference Model

Topic Maps: Human, not artificial, intelligence at work!