Re: [security-services] proposal wrt "status" and"send comments to the editor"

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

At 03:32 PM 1/6/02 -0800, Jeff Hodges wrote:
>The present doc set format includes this line on the first page..
>
>   "Status: Interim draft; send comments to the editor"
>
>
>After thinking about it for a bit, I have the following interrelated
>suggestions. My apologies for not bringing this up earlier.

I think I started adding this line to specs as a placeholder when I started 
doing my "stylistic thing" on them, so it hasn't been around that 
long.  (There was practically nothing along those lines before that time!)

>1. Rather than encourage readers to send comments to the editors 
>privately, I feel we should encourage that they send comments to a place 
>where we can all see them, and where they are archived. I think this will 
>be especially
>important for the doc set we plan to advertise here on 9-Jan.
>
>We already have an archived list set up for the world-at-large to send
>comments..
>
>   security-services-comment@lists.oasis-open.org
>
>   archive: http://lists.oasis-open.org/archives/security-services-comment/
>
>
>I suggest we add a few new lines to the first page of the present doc set to
>REPLACE "send comments to the editor", e.g...
>
>   Send comments to: security-services-comment@lists.oasis-open.org
>
>Also, doc editors should subscribe to that list.

I seem to recall some weirdness about the way these x-comments lists are 
set up -- it may be that they're just aliases that send things directly to 
the x list on the senders' behalf, since non-OASIS members can't join OASIS 
lists, and that they're not something you can subscribe to.  In any case, I 
think listing this address is a good idea, but see more below.

>2. Change "Status:" to "Maturity Level:", and use the proposed maturity 
>level terminology from this message thread..
>
>   updated -- proposed schedule. plus"committee last call" process
>   http://lists.oasis-open.org/archives/security-services/200112/msg00075.html
>
>Maturity level values described in that proposal are..
>
>   "committee working draft"             -- where the docs are now
>
>   "candidate committee specification"   -- upon entry to Last Call, and 
> on thru
>LC
>                                            if no showstopper normative 
> technical
>                                            issues are found
>
>   "committee specification"             -- after LC, and once all 
> non-normative
>                                            editing is complete, and docs are
>                                            voted to this maturity level.

My idea in putting a Status: section on the first page was something like 
W3C's "Status of This Document" section, where you have a novel (not 
boilerplate) description of what's going on with the draft, what's been 
substantively changed, what sort of feedback is wanted, where to send 
comments, etc.

I think it's a good idea (now that we have a canonical set of maturity 
levels) to have a line for it, but I also think the Status blurb is a good 
idea.  If we want to do this, though, we'll have to hop to it because it 
means writing some real text.

>So, this would yield something like this on the first doc pages...
>                 --------------------------
>   Document identifier: ...
>
>   Location: ...
>
>   Publication Date: ...
>
>   Maturity Level: Committee Working Draft
>
>   Send comments to: security-services-comment@lists.oasis-open.org
>
>   Editors: ...
>
>   Contributors: ...

(I like separating the editors and contributors, BTW.  We do need to 
rationalize our contributors' lists; I think Phill had suggested we use the 
list of people who regularly attend meetings.)

Could we add a "Status:" blurb at the end of this list?

Oh, and should we or should we not have revision tables anywhere in these 
drafts?  I moved them to the first pages, but they don't have to be 
there.  In most cases, they don't provide any information that will help 
anyone decipher our drafts any more successfully...

Finally, we should beware that the bibliographic references to other SAML 
drafts that appear in all our specs go "stale" quickly because the URLs in 
them mention draft numbers (e.g., bindings-08).  We need to check them all 
before we go live.  If we were to copy over each latest published draft 
into a generic "sstc-draft-bindings.pdf" file (etc.), it would be 
convenient then to change all the bib stuff once more, for good.

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