Re: Guidance and Rationale

["Eve L. Maler" <eve.maler@east.sun.com>]

At 06:50 PM 3/21/01 -0800, Darren Platt wrote:
>On the Use Cases and Requirements working group concall this morning we came
>up with a couple of issues that we thought we should open up to the TC at
>large for discussion.   Both issues are about adding new sections or content
>to the specification.  I will try to represent what was discussed, but I'm
>sure I'll miss some of it ...
>
>1. Rationale.  It was thought on the call that a section for rationale would
>be useful to people who review and/or implement our standard.  It was
>pointed out how Bruce Schneier recently criticized the IPSEC specification
>for not explaining why certain decisions were made.  It was also pointed out
>that the TC has limited bandwidth and writing up rationales may not be the
>most expedient use of our time.  Perhaps it would be useful to explain the
>rationale for only a few key areas.

There are definitely two schools of thought on this.

Stephen F. was saying at the F2F that he wants to avoid delivering a 
"brick" of a document.  I believe that rationale material is a great thing, 
but nearly all of it doesn't belong in the spec proper because it is hard 
to keep the normative and non-normative (rationale) material straight, and 
because it swells the size of the spec.  If we have any rationales written 
up, I would very much like to publish them, but as an accompanying 
document, not as part of the "real" spec.

The usual exception is in an introductory section where you're motivating 
the scope of the spec as a whole.  Introductions don't have a lot of 
normative stuff in them anyway, and providing a bit of conceptual 
background/bias is useful.

>2. Guidance.  It was thought that this may be a solution for requirements
>which are not made part of our specification.  There may be some
>requirements which do not make it into the spec, for example R-Disclosure,
>that we would like to make sure are not made impossible by the
>specification.  In the example of R-Disclosure, we may not make it a
>requirement that all implementations only disclose the attributes about a
>user which the user has given them permission to disclose.  We do, however,
>want this type of functionality possible in a given implementation.  The
>guidance section would describe how such requirements could be implemented
>'on top of' SAML.

Again, this sounds like a great candidate for an additional 
document.  (Unless the non-requirement ends up being a "SHOULD" instruction 
in the spec anyway, which does have a normative meaning...)

We should feel free to produce tutorials, best practices documents, etc. in 
addition to "the one true SAML spec."  I think breaking it down like this 
will help readers anyway, because each document is less to swallow.

My n cents,

         Eve
--
Eve Maler                                             +1 781 442 3190
Sun Microsystems XML Technology Development  eve.maler @ east.sun.com