OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

chairs message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


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>



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC