RE: [chairs] Oasis document identifiers - conclusion!

["Philpott, Robert" <rphilpott@rsasecurity.com>]

Dan - I think you missed a nuance of Eve's recommendation.  You also did not
factor in the OASIS-approved document number in your examples.  Was that
intentional? which has been discussed on the list. Eve did not include a
"-os" for oasis-approved standard.  For those docs, the oasis-approved
document ID gets prepended to the file name with an "oasis-" label.  

> OASIS Standard stage:
>    oasis-####-odrxml-charter-1.0.doc
>    oasis-####-odrxml-charter-1.0.pdf

I actually prefer this over the "-os" suggestion since it makes a clear
distinction between draft or cs specs and final approved standards.  Also,
"os" and "cs" look a bit too much alike and may cause confusion.

Rob Philpott 
RSA Security Inc. 
The Most Trusted Name in e-Security 
Tel: 781-515-7115 
Mobile: 617-510-0893 
Fax: 781-515-7020 
mailto:rphilpott@rsasecurity.com 


> -----Original Message-----
> From: Daniel Greenwood [mailto:dang@mit.edu]
> Sent: Sunday, January 12, 2003 11:24 PM
> To: Eve L. Maler; chairs@lists.oasis-open.org
> Subject: RE: [chairs] Oasis document identifiers - conclusion!
> 
> I am also in complete agreement with Eve's proposal.
> 
> Just to be sure we're all on the same page, and the proposal is
> complete, I have assumed that this naming scheme is intended to
> include final Oasis Standards (which I further assume should be
> denoted as "os").  I scratched out a fuller example below (primarily
> to illustrate to my own satisfaction how this would actually play
> out), which I share to see if it is correct.
> 
> I have further assumed that there would be no "-diff" designations for
> official Oasis Standards or Technical Committee Specifications -
> because they are in fact "final" stand alone documents.  But I have
> applied the "-diff" suffix to draft documents (including draft
> spec/standards), different where versions of the same document must be
> dealt with, and a "red-lined" version to show changes is helpful.
> 
> Along the same lines, I don't understand the need for any additional
> trailing version information after a "cs" or "os" document, as those
> designations mean the document has already been voted upon by OASIS or
> agreed upon by the TC and is final in THAT form.  A later final
> official version of an earlier final official standard or
> specification would be, I presume, "2.0" rather than "1.0".  So, I
> have removed the additional versioning information from the "os" and
> "cs" documents.  Is this not correct?
> 
> I've played out the naming scheme with two official documents: "blah"
> and "lala".  Blah goes on "all the way" to become an OASIS Standard
> (os), while the "lala" document plateaus as a Technical Committee
> Specification (cs).  There are drafts of both "blah" and "lala".
> Since there is, technically, no TC before a final charter exists, I
> have not bothered to apply a version chain to earlier drafts of a
> charter document (though individuals forming a TC certainly may wish
> to use the same convention) and I have called that phase the "TC
> Formation stage" rather than "standard stage" to be clearer about what
> has actually happened.  After the TC is formed, then the standards
> creation work begins during the "wording drafts" phase.
> 
> OASIS Standard stage:
>    odrxml-blah-1.0-os.html
>    odrxml-blah-1.0-os.pdf
> Committee Spec stage:
>    odrxml-blah-1.0-cs.html
>    odrxml-blah-1.0-cs.pdf
>    odrxml-lala-1.0-cs.html
>    odrxml-lala-1.0-cs.pdf
> Working drafts:
>    odrxml-blah-1.0-draft-03.html
>    odrxml-blah-1.0-draft-03-diff.html
>    odrxml-blah-1.0-draft-02.html
>    odrxml-blah-1.0-draft-02-diff.html
>    odrxml-blah-1.0-draft-01.html
>    odrxml-lala-1.0-draft-03.html
>    odrxml-lala-1.0-draft-03-diff.html
>    odrxml-lala-1.0-draft-02.html
>    odrxml-lala-1.0-draft-02-diff.html
>    odrxml-lala-1.0-draft-01.html
> OASIS TC formation stage:
>    odrxml-charter-1.0.html
> 
> A final note - I believe it is very important that any final agreement
> on semantic naming schemes include the "cs" phase as a separate
> designation, and not simply the "draft" or "os" phases.
> 
> I wonder: is the above "blah" and "lala" example a correct (or at
> least acceptable) extrapolation of how the proposal would be applied?
> 
> Thanks,
>  - Dan Greenwood, Chair of the eContracts TC
> 
> ==============================================
> |  Daniel J. Greenwood, Esq.
> |  Director, E-Commerce Architecture Program
> |  MIT School of Architecture and Planning
> |  77 Massachusetts Avenue, Room 7-231
> |  Cambridge, MA 02139
> |     http://ecitizen.mit.edu
> |     or http://www.civics.com
> |     dang@mit.edu
> ==============================================
> 
> -----Original Message-----
> From: Eve L. Maler [mailto:eve.maler@sun.com]
> Sent: Sunday, January 12, 2003 10:34 PM
> To: chairs@lists.oasis-open.org
> Subject: Re: [chairs] Oasis document identifiers - conclusion?
> 
> I'm sure the Kavi system will be wonderful and I agree that having
> proper metadata is the right thing to do, but it very much appeals to
> me
> to have a filenaming convention that works even when all you have is
> text editors, file directories, and browsers, with no cool
> registry/repository in the middle.  The web earned its success by
> working even in "roughing-it" circumstances, and I think we'll benefit
> by continuing to account for them.
> 
> jkeane wrote:
> > 1)  Have a meaningful name - no acronyms or abbreviations for
> contents.
> > Short TC names do makes sense.  I keep an archive of work products,
> pruning
> > out unnecessary documents and most drafts after the project is long
> over.
> > When you are browsing an older directory the Alzheimer effect kicks
> in after
> > six months.
> 
> Certainly it makes sense to avoid being cryptic.  However, I notice
> that
> the current OASIS web server seems to truncate long filenames when
> doing
> a directory display, losing critical information unless you hover over
> the link and observe the full link name in the browser footer bar.
> Can
> this truncation be fixed?
> 
> > 2)  We store related documents in project sub-directories.  This
> makes it
> > unnecessary to include extensive generic info in every file name.
> If you
> > store all the docs in a single directory, it would make more sense
> to have
> > the prime sort by TC name.
> 
> I was thinking that all the filenames of all the TC outputs should be
> distinguishable and unique even if they were put into one big pile.
> Thus, the TC ID should always appear in the filename because it serves
> as a "namespace" that disambiguates otherwise-similar filenames from
> different groups.  Project subdirectories are great if called for, but
> I'd think it would still be desirable to reflect those categories in
> their filenames.
> 
> >
> > 3) Include the date (as proposed, but in a sortable format)  File
> dates
> > change (i.e. moving all files from computer A to computer B for
> maintenance.
> 
> Yikes, I really hate putting publication dates in filenames.  W3C does
> that, and it's a really unwieldy and hard-to-mentally-sort device.  In
> the SAML group, we've just been using the trick of publishing 00, 01,
> 02, 03, etc. drafts, and I've been advocating it here because it has
> worked incredibly well.  That way, implementors can say "Our latest
> download conforms to draft 31, but we're prepared to change it to
> reflect the draft-34 changes by next Wednesday."  And in a meeting you
> can say "I move to accept draft 07 of this document as a Committee
> Spec."  The constantly increasing draft number gives more information
> at
> a glance than does the (frankly random) date on which publication
> occurred, and is way shorter.
> 
> > 4) Include version sequence in sortable format.  This will avoid
> confusion
> > about which drafts are on the table.
> 
> Agree.  Though so far we've been discussing allowing the {description}
> field to be anything the TC wants, so one way to go is to make
> recommendations (SHOULDs) about this, and another is to make fast
> rules
> (MUSTs) about it.
> 
> > 5) Add any relevant trailing info about status or special features.
> 
> Sure.
> 
> > Here is an example of what we used in drafting the Online Dispute
> Resolution
> > Charter. This approach has enabled me to work with ad hoc teams over
> many
> > projects over many years and not have too much confusion or spending
> time in
> > discussions (which we needed do here) like this.
> >
> > OdrXML Charter 1.0 DRAFT 2002.09.26.doc
> > OdrXML Charter 1.1 DRAFT 2002.10.07.doc
> > OdrXML Charter 1.2 DRAFT FINAL 2002.10.18.doc
> > OdrXML Charter 1.2 DRAFT FINAL REDLINE 2002.10.18.doc
> > OdrXML Charter 1.2a DRAFT FINAL 2002.10.19.doc
> > OdrXML Charter FINAL 2002.11.11.doc
> 
> Exposing my weirdnesses once again, I have an allergy to spaces in
> filenames.  Most systems and software handle them now, but a few old
> ones don't handle them so well.
> 
> I do agree with your ordering of the fields, though.
> 
> My preferences (including lowercase spelling :-) mapped onto your
> ordering would look (very) approximately like this:
> 
> Working drafts:
>    odrxml-charter-1.0-draft-01.doc
>    odrxml-charter-1.0-draft-02.doc
>    odrxml-charter-1.0-draft-03.doc
> Committee Spec stage:
>    odrxml-charter-1.0-cs-01.doc
>    odrxml-charter-1.0-cs-01-diff.doc
>    odrxml-charter-1.0-cs-01.pdf
> OASIS Standard stage:
>    oasis-####-odrxml-charter-1.0.doc
>    oasis-####-odrxml-charter-1.0.pdf
> 
> I would like to come to closure on this matter really soon because I
> don't have a lot more cycles to spend on it, but the problem is that
> we
> don't have a clearly defined decision-making authority responsible for
> this -- unless it's Karl?...
> 
>         Eve
> 
> --
> Eve Maler                                        +1 781 442 3190
> Sun Microsystems                            cell +1 781 354 9441
> Web Technologies and Standards               eve.maler @ sun.com
> 
> 
> ----------------------------------------------------------------
> To subscribe or unsubscribe from this elist use the subscription
> manager: <http://lists.oasis-open.org/ob/adm.pl>
> 
> 
> ----------------------------------------------------------------
> To subscribe or unsubscribe from this elist use the subscription
> manager: <http://lists.oasis-open.org/ob/adm.pl>