Re: [security-services] Editorial topics that need discussion

[John Kemp <john.kemp@earthlink.net>]

Eve (et al)

 From looking at [SAMLCore], it seems to me that one way to proceed  
would be to split out Section 1.3 SAML Concepts into a separate  
primer/overview document, and add a user-oriented example (similar to  
what Jeff did in the Liberty ID-FF Architecture Overview, and - I think  
- along the lines of what Krishna was suggesting). I don't imagine that  
would take so much time. It might also be helpful to take the sample  
message exchange from [SAMLBind] and develop that into a fully-fledged  
example (putting it into the overview/primer) that might describe the  
flows of the user-oriented example. Such a document might then also  
describe at a high-level the SAML document set, so that an implementor  
would have a good place to start.

We should, however, first think about whether implementors would be the  
audience for such a re-structuring. If not, then who would we target  
with such (a) document(s)? In fact, if a goal of SSTC is to "promote  
adoption of SAML" then I think one good way to encourage such adoption  
is to provide support documents around the normative specifications,  
that help place them in context, and explain what SAML is good for, and  
why...

Finally, one of the things that I think might be good for implementors  
is if the SAML documents were available as HTML, and hyper-linked  
appropriately. This would make it possible to easily link between  
documents as a complete set (another method would be to use PDF  
bookmarking in some tricky fashion). If one could easily link between  
documents that way, it would be possible to make easy, clickable  
reference to examples (possibly in another document) from the normative  
text, and vice-versa.

- JohnK

[SAMLCore]       Assertions and Protocol for the OASIS Security  
Assertion Markup Language v1.1, Committee Specification, 27 May 2003
[SAMLBind]       Bindings and Profiles for the OASIS Security Assertion  
Markup Language v1.1, Committee Specification, 27 May 2003


On Thursday, Aug 14, 2003, at 10:32 US/Eastern, Eve L. Maler wrote:

> The editorial folks have been bouncing around a few ideas, and I  
> wanted to bring them to the whole TC for discussion.  (Should these be  
> added explicitly to the work items document?  That document is feeling  
> almost like an issues list now...)  Perhaps we could spend a few  
> minutes on each at the next meeting.
>
> - Bindings/profiles spec reorganization.  We have talked before about  
> versioning implications of individual profiles.  I think it would be  
> more elegant, versioning-wise, to put the instructional material about  
> "what constitutes a profile" in the core spec, and then have  
> individual specs for each profile or set of related profiles.  If  
> we're going to be adding bindings, we might want to do the same thing  
> with them.  Another consideration is the breakdown of Liberty specs;  
> Jeff pointed out that we might want to follow that lead.  But he also  
> pointed out another consideration: speed of V2.0 vs. undertaking a  
> huge reorg.  We'll need to discuss the speed factor as part of our  
> goal statement discussion, methinks, and that will help to guide the  
> editorial choices.
>
> - Ease-of-use content.  I've suggested that we desperately need  
> examples in the core spec, and others have suggested that we produce a  
> tutorial.  What do people think is the best way to deliver this sort  
> of stuff: an examples appendix, examples interspersed among the  
> normative bits, a separate tutorial with examples, all of the above,  
> ...?  Are there materials out there that we could use as a basis?
>
> 	Eve
> --  
> Eve Maler                                        +1 781 442 3190
> Sun Microsystems                            cell +1 781 354 9441
> Web Products, Technologies, and Standards    eve.maler @ sun.com
> **********************************************************************
> SunNetwork 2003 Conference and Pavilion  http://www.sun.com/sunnetwork
> September 16-18, 2003                    Moscone Center, San Francisco
> An unparalleled event in network computing! Make the net work for you!
>
>
> You may leave a Technical Committee at any time by visiting  
> http://www.oasis-open.org/apps/org/workgroup/security-services/ 
> members/leave_workgroup.php
>