RE: [odata] Second level documents

["Ram Jeyaraman (MS OPEN TECH)" <Ram.Jeyaraman@microsoft.com>]

Per TC decision during the meeting today, the "Temporary files" folder has been renamed to "Proposals".

https://www.oasis-open.org/apps/org/workgroup/odata/documents.php 

As discussed during the meeting, please use this folder for documenting verbose descriptions, comments, proposals, or resolutions on issues, and link to those documents from JIRA issues (from the description, comment, proposal, or resolution issue fields).

Thanks, Robin, for your feedback, and Stefan, for driving this to closure!

-----Original Message-----
From: odata@lists.oasis-open.org [mailto:odata@lists.oasis-open.org] On Behalf Of Stefan Drees
Sent: Thursday, August 23, 2012 12:21 AM
To: Ram Jeyaraman (MS OPEN TECH)
Cc: Robin Cover; odata@lists.oasis-open.org; Stefan Drees
Subject: [odata] Second level documents

Dear Ram,

since I seem to be responsible for the first impulse to step into the 
direction of further structuring the kavi document area (which is 
accessible through the web to upload and store documents of and for the 
TC) I think I should comment on this before the meeting.

First of all:
Thanks a lot Ram, for creating a folder with a first candidate name to 
"support our second level documentation needs" just because I "whined" 
in a comment ;-).

Use case:
When eg. pumping review feedback items in the order of 20 to 50 into the 
comment section of a JIRA Issue, I prefer structured text (like Mardown 
etc) others may enjoy these documents in a formatted layout like html. 
So I link inside the Issue-Comment to this optional view I personally 
keep in sync with the issue comment's content.

I consider the content of the issue as the normative version of a 
"second level document" and the html (the stuff I uploaded into the 
document area) as an optional additional format that we are so nice to 
offer and keep in sync with the normative document (the comment in the 
issue) via revisioning.

So I guess it is only a naming problem.

I propose to name such a folder (as described above) "Issue Support" or 
"Member Reviews" or simply "Reviews" ... at least for the use case I 
stumpled upon.

I think the kavi folders are a valuable structuring help to separate 
secondary from primary documents and ensure the web interface remains 
usable and in good shape.

All the best,
Stefan Drees.

Historic details (and sorry for top posting):

Am 23.08.12 01:09, schrieb Ram Jeyaraman (MS OPEN TECH):
> Good feedback. I will raise this question at the TC meeting tomorrow and
> pick a name that does not imply temporality.
>
> Thanks.
>
> *From:*odata@lists.oasis-open.org [mailto:odata@lists.oasis-open.org]
> *On Behalf Of *Robin Cover
> *Sent:* Wednesday, August 22, 2012 4:05 PM
> *To:* Ram Jeyaraman (MS OPEN TECH)
> *Cc:* odata@lists.oasis-open.org; Robin Cover
> *Subject:* Re: [odata] "Temporary files" folder
>
> Hi Ram (and TC).
>
> While I'm not certain about the function of the new Folder named
> "Temporary files", I wonder whether that name might convey the
> notion of "transient, ephemeral, impermanent, may-be-deleted."
>
> Such interpretation would be unfortunate, since the OASIS rules
> and Policies require that resources uploaded to any publication
> venue must remain intact and must not be deleted [1].  It's
> SOP and good hygiene in most venues, but essential in the
> OASIS context based upon the Policy definitions.
>
> So for your consideration, I might encourage adoption of a folder
> name like "Proposals" which would not connote possible removal.
>
> I do think you should be able to move resources from the
> Folder to some other Folder at a later time, as may be warranted,
> and that doing so will not break the link, which is required to
> be persistent [2]
>
> Let me know if you have any questions.
>
> Thanks!
>
> - Robin Cover
>
> Robin Cover
> OASIS, Director of Information Services
> Editor, Cover Pages and XML Daily Newslink
> Email: robin@oasis-open.org <mailto:robin@oasis-open.org>
> Staff bio: http://www.oasis-open.org/people/staff/robin-cover
> Cover Pages: http://xml.coverpages.org/
> Newsletter: http://xml.coverpages.org/newsletterArchive.html
> Tel: +1 972-296-1783
>
> [1] Resource Permanence
> http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#resourcePermanence
>
> As part of the OASIS commitment to transparency, openness,
> and accountability, resources published in the OASIS
> Library, TC Document Repository, and other venues must
> not be deleted or otherwise altered. All revisions are
> retained. With the exception of resources identified by
> "latest version" URI aliases, content instantiated as
> regular files and directories must not be over-written,
> replaced, renamed, or removed. TC Members are expected
> to follow this rule even in cases where a collaboration
> tool (by some means) might allow resource deletion.
> [OASIS Library: http://docs.oasis-open.org/
> TC Document Repository:
> http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#tc-document-repository
> ]
>
> [2] URI Persistence
> http://docs.oasis-open.org/specGuidelines/ndr/namingDirectives.html#URI-persistence
>
> Corollary to Resource Permanence, URIs for published OASIS
> resources must be persistent. All resources and the
> Uniform Resource Identifiers (URIs) which establish
> mappings from identifiers to resources are permanent.
> This rule also applies to any secondary resource identified
> by a fragment identifier. Assignment of URIs to resources
> is thus considered to be inviolate other than for URI
> aliases intentionally associated with variable content.
> For all other URIs, no action which severs the relationship
> between a URI and the resource may be undertaken.
>
>
> On Wed, Aug 22, 2012 at 5:48 PM, Ram Jeyaraman (MS OPEN TECH)
> <Ram.Jeyaraman@microsoft.com <mailto:Ram.Jeyaraman@microsoft.com>> wrote:
>
> A new "Temporary files" folder [1] is now available in the TC document
> repository. This is in response to some earlier comments (from Stefan)
> about the need for such temporary folders. We can use the folder for
> parking proposals, etc. Take a look; we can rename the folder (call it
> scratch, temp, proposals, etc.), if we so choose.
>
> [1]
> https://www.oasis-open.org/apps/org/workgroup/odata/documents.php?folder_id=2681
>
>
>
>
>
> --
>