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

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

Hi John-- These are great comments.  I wanted to note, first of all, 
that Frederick has offered to work on a SAML primer, so assuming we come 
to the conclusion that this is what we want, we've got at least one 
offer of help.

Several ideas are converging here.  In the last meeting we talked about 
doing substantial new editorial work, and we also talked about 
developing outreach materials.  You're pointing out that we need to be 
clear about our various audiences.  (Recall that I had taken an AI to 
send mail to those people who were interested in being on an "outreach 
task force"; JeffH had suggested that we just conduct editorial team 
discussions on the main TC list, and I'm getting the idea that we should 
conduct outreach discussions here too.)

My feeling is that we need to cater to at least two different audiences:

- Implementors who want to achieve conformant implementations. They need 
not only solid normative text, but also supporting conceptual/tutorial 
material and examples.  They would be the target for a SAML Primer (for 
which your suggestions are excellent).  It's their needs we need to 
consider in looking at any spec restructuring and hypertext ease of use.

- Those making a technology selection for which SAML is a contender. 
This is where outreach deliverables come in.

Here is a suggestion off the top of my head for outreach deliverables:

Website (I'm hoping Rob is still up for doing website stuff even
if it involves this much work!):
- Refresh content
- Ongoing links on the home page to relevant documents (the doc
   repository interface is a nightmare)
- Link to Liberty contribution and related info (already an AI)
- Links to other efforts based on SAML
- Add Press section; possibly use this section for links to
   commercial white papers, noting whether registration is
   required
- Add Implementations section and link to APIs and toolkits
- Publish SAML V2.0 scope statement/mission when done with it

Collateral:
- Finish and publish FAQ (Sep 2 deadline for first draft; Krishna
   has volunteered)
- Collect and publish SAML case studies
- Develop "Why SAML?" material

PR:
- Write and submit monthly (ideally) OASIS News notices (we should
   have some more SAML V1.1 news soon, e.g.)
- Plan out any future interop events
- Possibly set up analyst briefings

Since we could go in about seventeen different directions with all of 
these considerations, let me suggest a set of things the group needs to 
decide on in the next meeting so we can make progress:

- Get agreement on the V2.0 mission statement (I'm particularly
   interested in how highly we would rank "urgency/speed", since
   that would impact both the new-design load and the editorial
   load we can take on)
- Get agreement on the audience(s) we want to address
- Build an initial rough list of new deliverables and assign them
   out

Those who sign up for any kind of editorial task could then confer in 
email (on the TC list) regarding matters such as how to "code" the 
documents, what any restructuring should look like, etc.

What do you think?

	Eve

John Kemp wrote:

> 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
-- 
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!