Off-topic: Re: Comments on Auth 2.0 - Pre-Draft 11

[Eve L. Maler]

As a general point and FWIW, capitalized ("RFC 2119") uses of MUST, 
SHOULD, etc. are meant to make it easy to form testable assertions 
for compliance-checking.  It's best to avoid redundant normative 
spec content, though sometimes repetition or restatement in the 
right places can reinforce a correct interpretation for better 
interop.  And it's best to use non-RFC 2119 ways of conveying 
expectations and best practices precisely in the set of cases where 
something isn't testable (e.g., it's an internal operation of a 
system entity and thus isn't amenable to standardization, or it 
involves some kind of subjective judgment).

If you really mean something normative, using capitals is safest 
even if it seems ugly...  Readers will just want it to be 
consistent, so a final editing pass ideally will include a review of 
this.  If there's some doubt what lowercase versions of the words 
mean, you could add notation wording like what SAML V1.x used:

=====
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
specification are to be interpreted as described in IETF RFC 2119 
[RFC 2119]:

     …they MUST only be used where it is actually required for 
interoperation or to limit behavior which has potential for causing 
harm (e.g., limiting retransmissions)…

These keywords are thus capitalized when used to unambiguously 
specify requirements over protocol and application features and 
behavior that affect the interoperability and security of 
implementations. When these words are not capitalized, they are 
meant in their natural-language sense.
=====

But this was removed in SAML2, since it was assumed readers know the 
drill.

Richard Mitchell noted thirty years ago that discursive prose is a 
technology.[1]  Technical specs are even more so!  (If you're not 
familiar with the Underground Grammarian, I strongly RECOMMEND his 
Less Than Words Can Say[2]...)

	Eve

[1] http://www.sourcetext.com/grammarian/less-than-words-can-say/03.htm
[2] http://www.sourcetext.com/grammarian/index.html

Josh Hoyt wrote:
> On 12/14/06, Joaquin Miller <joaquin at netmesh.us> wrote:
>>> I have changed that text from "needs to" to MUST, although I think that the
>>> sentence before that (The end user's input MUST be normalized into an
>>> Identifier) is pretty unambiguous.
>>  I feel this is an excellent change.  This style should be followed
>> throughout.
>>
>>  The problem with 'needs to' and 'MUST' in the same document is that it
>> leaves the reader this little puzzle to puzzle over:  What is the normative
>> difference between 'needs to' and 'MUST'?  Why is 'needs to' used here and
>> 'MUST' there?  Is 'needs to' weaker than 'MUST'? Is 'needs to' stronger than
>> 'SHOULD'?
> 
> I doubt that the "needs to" wording would have ever caused any
> problems with implementation. The sentence before states that you MUST
> normalize the input. The "needs to" was describing a condition that is
> necessary to check in order to perform the normalization. Anyone who
> was attempting to implement the normalization algorithm would see that
> it is necessary to determine the type of the input before continuing.
> 
> I think that words like MUST and SHOULD are not necessary when
> describing how to do something whose importance has already been made
> clear (by a MUST, etc.). I have a hard time reading prose that uses
> those words excessively, because if they are over-used, they become
> noise ("you already said I MUST normalize").
> 
> Anyway, I think the OpenID 2.0 Authentication specification is pretty
> consistent about using the appropriately strong wording when it's not
> already clear whether something is required, so I think this
> discussion is mostly academic. Feel free to make requests if there are
> specific parts whose compliance is not obvious.
> 
> Josh
-- 
Eve Maler                                         +1 425 947 4522
Technology Director                           eve.maler @ sun.com
CTO Business Alliances group                Sun Microsystems, Inc.